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

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

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

Możesz wysyłać wiadomości z ładunkiem powiadomienia składającym się z predefiniowanych pól, ładunkiem danych zawierającym własne pola zdefiniowane przez użytkownika lub wiadomość zawierającą oba typy ładunków. Więcej informacji znajdziesz w artykule Typy wiadomości.

Autoryzowanie żądań wysyłania HTTP v1

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

  • Domyślne uwierzytelnianie 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 Twoja aplikacja działa w Compute Engine, Google Kubernetes Engine, App Engine, lub Cloud Functions (w tym Cloud Functions for Firebase), użyj domyślnego uwierzytelniania aplikacji (ADC). ADC używa Twojego dotychczasowego domyślnego konta usługi do uzyskiwania danych logowania na potrzeby autoryzowania żądań. Umożliwia też elastyczne testowanie lokalne za pomocą zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS. Aby w pełni zautomatyzować proces autoryzacji, użyj ADC razem z bibliotekami serwera pakietu Admin SDK.

Jeśli Twoja aplikacja działa w środowisku serwera innego niż Google, musisz pobrać plik JSON konta usługi z projektu w Firebase. Dopóki masz dostęp do systemu plików zawierającego plik klucza prywatnego, możesz używać zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS do autoryzowania żądań 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 dużą ostrożnością ze względu na ryzyko ujawnienia danych logowania.

Podawanie danych logowania za pomocą ADC

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

  1. ADC sprawdza, czy jest ustawiona zmienna środowiskowa GOOGLE_APPLICATION_CREDENTIALS. Jeśli zmienna jest ustawiona, ADC używa pliku konta usługi, na który wskazuje ta 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 ADC nie może użyć żadnych z tych danych logowania, system zgłasza błąd.

Ten przykład kodu pakietu Admin SDK ilustruje tę strategię. Przykład nie określa wyraźnie danych logowania aplikacji. ADC może jednak 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żywać danych logowania uzyskanych za pomocą tego konta usługi do autoryzowania żądań serwera.

Wszystkie konta usługi w projekcie w Firebase możesz wyświetlić w ustawieniach > Konta usługi na karcie.

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 konsoli Firebase otwórz ustawienia na karcie Ustawienia > Konta usługi.

  2. Kliknij Wygeneruj nowy klucz prywatny, a następnie 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 podania danych logowania aplikacji. Możesz ustawić zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS lub wyraźnie 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 dotyczy tylko 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 czynności domyślne uwierzytelnianie aplikacji (ADC) może niejawnie określić Twoje dane logowania, co pozwoli Ci używać danych logowania konta usługi podczas testowania lub uruchamiania w środowiskach innych niż Google.

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

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

Użyj danych logowania Firebase razem 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

Gdy token dostępu wygaśnie, automatycznie zostanie wywołana metoda odświeżania tokena, aby pobrać zaktualizowany token dostępu.

Aby autoryzować dostęp do FCM, poproś o zakres https://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 konta usługi z innego projektu

Możesz wysyłać wiadomości w jednym projekcie („projekt docelowy”), używając tokena OAuth 2.0 wygenerowanego na podstawie konta usługi w innym projekcie („projekt nadawcy”). Pozwoli Ci to scentralizować zarządzanie kontami usługi w jednym projekcie, a jednocześnie wysyłać wiadomości w imieniu innych. Aby to zrobić, wykonaj te czynności:

  1. W projekcie nadawcy upewnij się, że interfejs Komunikacja w chmurze Firebase (FCM) API jest włączony. Sprawdź, czy jest włączony w konsoli Firebase, otwierając Ustawienia > Ogólne. Następnie kliknij kartę Komunikacja w chmurze.

  2. W projekcie nadawcy utwórz konto usługi.

  3. W projekcie docelowym przypisz rolę Administrator interfejsu Komunikacji w chmurze Firebase (FCM) API do adresu e-mail konta usługi. Zrobisz to w konsoliGoogle Cloud na stronie Administracja > Uprawnienia. Ta rola umożliwia kontu usługi z projektu nadawcy wysyłanie wiadomości do projektu docelowego.

  4. Wygeneruj token dostępu OAuth 2.0 dla konta usługi w projekcie nadawcy. Możesz to zrobić na jeden z tych sposobów:

    • Pobierz i użyj pliku JSON klucza konta usługi.
    • Jeśli Twoja usługa działa w Google Cloud, użyj Workload Identity.

  5. Użyj uzyskanego tokena dostępu w nagłówku Authorization żądania wysyłania. Żądanie musi zostać wysłane do punktu końcowego HTTP v1 w projekcie docelowym:

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

Wysyłanie wiadomości na konkretne urządzenia

Aby wysłać wiadomość 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 z powiadomieniem za pomocą interfejsu FCM HTTP v1 API

Z tej sekcji dowiesz się, 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

Pełny przykład żądania HTTP w formacie JSON

Oto pełny przykład pokazujący, jak opublikować powiadomienie w żądaniu 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

Aby wypróbować przykład w narzędziu APIs Explorer , kliknij Uruchom.