Wysyłanie wiadomości za pomocą interfejsu FCM HTTP v1 API

Za pomocą FCM interfejsu HTTP v1 API możesz tworzyć żądania wiadomości i wysyłać je do tych typów miejsc docelowych:

  • Nazwa tematu
  • Stan
  • Token rejestracji urządzenia
  • Nazwa grupy urządzeń (tylko protokół)

Możesz wysyłać wiadomości z ładunkiem powiadomienia składającym się ze wstępnie zdefiniowanych pól, ładunkiem danych zawierającym zdefiniowane przez Ciebie pola lub wiadomości zawierające oba rodzaje ładunków. Więcej informacji znajdziesz w sekcji Typy wiadomości.

Autoryzowanie żądań wysyłania HTTP w wersji 1

W zależności od szczegółów środowiska serwera użyj kombinacji tych strategii, aby autoryzować żądania serwera do usług Firebase:

  • Domyślne dane logowania aplikacji Google (ADC)
  • plik JSON konta usługi,
  • Krótkotrwały token dostępu OAuth 2.0 pochodzący z konta usługi.

Jeśli aplikacja działa w Compute Engine, Google Kubernetes Engine, App Engine lub Cloud Functions (w tym Cloud Functions for Firebase), użyj domyślnych danych logowania aplikacji (ADC). ADC używa istniejącego domyślnego konta usługi do uzyskiwania danych logowania w celu autoryzowania żądań. Umożliwia też elastyczne testowanie lokalne za pomocą zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS. Aby w pełni zautomatyzować proces autoryzacji, używaj ADC w połączeniu z bibliotekami serwera pakietu Admin SDK.

Jeśli Twoja aplikacja działa w środowisku serwera innego niż Google, musisz pobrać z projektu Firebase plik JSON konta usługi. Jeśli masz dostęp do systemu plików zawierającego plik klucza prywatnego, możesz użyć zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS, aby autoryzować żądania za pomocą tych ręcznie uzyskanych danych logowania. Jeśli nie masz dostępu do takiego pliku, musisz odwołać się do pliku konta usługi w kodzie. Należy to zrobić z najwyższą ostrożnością ze względu na ryzyko ujawnienia danych logowania.

Podawanie danych logowania za pomocą ADC

Domyślne uwierzytelnianie aplikacji Google (ADC) sprawdza Twoje dane logowania w tej kolejności:

  1. ADC sprawdza, czy zmienna środowiskowa GOOGLE_APPLICATION_CREDENTIALS jest ustawiona. Jeśli zmienna jest ustawiona, ADC używa pliku konta usługi, na który wskazuje zmienna.

  2. Jeśli zmienna środowiskowa nie jest ustawiona, ADC używa domyślnego konta usługi, które Compute Engine, Google Kubernetes Engine, App Engine i Cloud Functions udostępniają aplikacjom działającym w tych usługach.

  3. Jeśli domyślne dane logowania aplikacji nie mogą użyć żadnych z powyższych danych logowania, system zgłosi błąd.

Poniższy przykładowy kod pakietu Admin SDK ilustruje tę strategię. W przykładzie nie podano wyraźnie danych logowania aplikacji. Jednak ADC może niejawnie znaleźć dane logowania, o ile zmienna środowiskowa jest ustawiona lub aplikacja działa w Compute Engine, Google Kubernetes Engine, App Engine lub Cloud Functions.

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}
init.go

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

Ręczne podawanie danych logowania

Projekty Firebase obsługują konta usługi Google, których możesz używać do wywoływania interfejsów API serwera Firebase z serwera aplikacji lub zaufanego środowiska. Jeśli tworzysz kod lokalnie lub wdrażasz aplikację lokalnie, możesz użyć danych logowania uzyskanych za pomocą tego konta usługi, aby autoryzować żądania serwera.

Aby uwierzytelnić konto usługi i przyznać mu uprawnienia dostępu do usług Firebase, musisz wygenerować plik klucza prywatnego w formacie JSON.

Aby wygenerować plik klucza prywatnego dla konta usługi:

  1. W Firebase konsoli otwórz Ustawienia > Konta usługi.

  2. Kliknij Wygeneruj nowy klucz prywatny, a potem potwierdź, klikając Wygeneruj klucz.

  3. Bezpiecznie przechowuj plik JSON zawierający klucz.

Podczas autoryzacji za pomocą konta usługi masz 2 możliwości przekazania danych logowania do aplikacji. Możesz ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS lub jawnie przekazać ścieżkę do klucza konta usługi w kodzie. Pierwsza opcja jest bezpieczniejsza i zdecydowanie zalecana.

Aby ustawić zmienną środowiskową:

Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę pliku JSON zawierającego klucz konta usługi. Ta zmienna jest stosowana tylko w bieżącej sesji powłoki, więc jeśli otworzysz nową sesję, ustaw ją ponownie.

Linux lub macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

W PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Po wykonaniu powyższych kroków domyślne dane logowania aplikacji (ADC) będą mogły niejawnie określać Twoje dane logowania, co umożliwi Ci używanie danych logowania konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.

Używanie danych logowania do tworzenia tokenów dostępu

Jeśli nie używasz biblioteki Firebase Admin SDK, która automatycznie obsługuje autoryzację, musisz wygenerować token dostępu i dodać go do wysyłanych żądań.

Użyj danych logowania Firebase wraz z biblioteką Google Auth Library w preferowanym języku, aby pobrać krótkotrwały token dostępu OAuth 2.0:

node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    const key = require('../placeholders/service-account.json');
    const jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}
index.js

W tym przykładzie biblioteka klienta interfejsu Google API uwierzytelnia żądanie za pomocą tokena sieciowego JSON (JWT). Więcej informacji znajdziesz w artykule Tokeny sieciowe JSON.

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
  request = google.auth.transport.requests.Request()
  credentials.refresh(request)
  return credentials.token
messaging.py

Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refresh();
  return googleCredentials.getAccessToken().getTokenValue();
}
Messaging.java

Po wygaśnięciu tokena dostępu automatycznie wywoływana jest metoda odświeżania tokena w celu pobrania zaktualizowanego tokena dostępu.

Aby autoryzować dostęp do FCM, poproś o zakreshttps://www.googleapis.com/auth/firebase.messaging.

Aby dodać token dostępu do nagłówka żądania HTTP:

Dodaj token jako wartość nagłówka Authorization w formacie Authorization: Bearer <access_token>:

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

Python

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}
messaging.py

Java

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;
FirebaseMessagingSnippets.java

Autoryzowanie za pomocą konta usługi z innego projektu

Możesz wysyłać wiadomości w ramach jednego projektu („projekt docelowy”), używając tokena OAuth 2.0 wygenerowanego na podstawie konta usługi w innym projekcie („projekt nadawcy”). Pozwala to scentralizować zarządzanie kontami usługi w jednym projekcie, a jednocześnie wysyłać wiadomości w imieniu innych osób. Aby dowiedzieć się, jak to zrobić, wykonaj te czynności:

  1. Włącz interfejs API: sprawdź, czy interfejs Firebase Cloud Messaging API jest włączony w projekcie nadawcy.
  2. Utwórz konto usługi: utwórz konto usługi w projekcie nadawcy.
  3. Przyznaj uprawnienia: w projekcie docelowym przyznaj adresowi e-mail konta usługi rolę Administrator interfejsu Firebase Cloud Messaging API na stronie Uprawnienia. Dzięki temu konto usługi z innego projektu może wysyłać wiadomości do projektu docelowego.
  4. Uzyskiwanie tokena: wygeneruj token dostępu OAuth 2.0 dla konta usługi w projekcie nadawcy. Możesz to zrobić na jeden z tych sposobów:
    • Pobieranie i używanie pliku JSON z kluczem konta usługi.
    • Możesz też użyć Workload Identity, jeśli usługa działa w Google Cloud.
  5. Wyślij prośbę: użyj uzyskanego tokena dostępu w nagłówku Authorization wysyłanej prośby. Żądanie musi być wysłane do punktu końcowego HTTP v1 projektu docelowego: 
        POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send

Wysyłanie wiadomości na określone urządzenia

Aby wysłać powiadomienie na jedno konkretne urządzenie, przekaż token rejestracji urządzenia w sposób pokazany poniżej.

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

Polecenie cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

W przypadku powodzenia odpowiedź interfejsu HTTP v1 API jest obiektem JSON zawierającym identyfikator wiadomości:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

Wysyłanie testowej wiadomości powiadomienia za pomocą interfejsu FCM HTTP v1 API

W tej sekcji opisaliśmy, jak wysłać testową wiadomość z powiadomieniem za pomocą interfejsu FCM HTTP v1 API.

Adres URL żądania HTTP

Żądanie składa się z żądania HTTP POST do określonego miejsca docelowego (tokena rejestracji, tematu lub warunku) pod tym adresem URL:

POST https://fcm.googleapis.com/v1/projectId/messages:send

Przykładowy plik JSON z pełnym żądaniem HTTP

Oto pełny przykład pokazujący, jak wysłać powiadomienie w ramach żądania HTTP POST:

{
  "message": {
    "token": REGISTRATION_TOKEN,
    "notification": {
      "title": "FCM API test",
      "body": "This is the body of the notification.",
      "image": "https://cat.10515.net/1.jpg"
    }
  }
}

Uruchom

Kliknij Uruchom, aby wypróbować przykład w API Explorer.