Nachricht mit der FCM HTTP v1 API senden

Mit der FCM HTTP v1-API können Sie Nachrichtenanfragen erstellen und an die folgenden Arten von Zielen senden:

  • Name des Themas
  • Bedingung
  • Geräteregistrierungstoken
  • Name der Gerätegruppe (nur Protokoll)

Sie können Nachrichten mit einer Benachrichtigungsnutzlast aus vordefinierten Feldern, einer Datennutzlast aus benutzerdefinierten Feldern oder einer Nachricht mit beiden Arten von Nutzlast senden. Weitere Informationen finden Sie unter Nachrichtentypen.

HTTP v1-Sendeanfragen autorisieren

Je nach den Details Ihrer Serverumgebung verwenden Sie eine Kombination dieser Strategien, um Serveranfragen an Firebase-Dienste zu autorisieren:

  • Google-Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC)
  • Eine JSON-Datei für das Dienstkonto
  • Ein kurzlebiges OAuth 2.0-Zugriffstoken, das von einem Dienstkonto abgeleitet wurde

Wenn Ihre Anwendung auf Compute Engine, Google Kubernetes Engine, App Engine oder Cloud Functions (einschließlich Cloud Functions for Firebase) ausgeführt wird, verwenden Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC). ADC verwendet Ihr vorhandenes Standarddienstkonto, um Anmeldedaten zum Autorisieren von Anfragen abzurufen. Außerdem ermöglicht ADC flexible lokale Tests über die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS. Um den Autorisierungsablauf vollständig zu automatisieren, verwenden Sie ADC zusammen mit Admin SDK-Serverbibliotheken.

Wenn Ihre Anwendung auf einer Nicht-Google-Serverumgebung ausgeführt wird, müssen Sie eine JSON-Datei für das Dienstkonto aus Ihrem Firebase-Projekt herunterladen. Solange Sie Zugriff auf ein Dateisystem mit der Datei für den privaten Schlüssel haben, können Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS verwenden, um Anfragen mit diesen manuell abgerufenen Anmeldedaten zu autorisieren. Wenn Sie keinen solchen Dateizugriff haben, müssen Sie in Ihrem Code auf die Dienstkontodatei verweisen. Dies sollte jedoch mit äußerster Sorgfalt erfolgen, da das Risiko besteht, dass Ihre Anmeldedaten offengelegt werden.

Anmeldedaten mit ADC bereitstellen

Die Google-Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) suchen in der folgenden Reihenfolge nach Ihren Anmeldedaten:

  1. ADC prüft, ob die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festgelegt ist. Ist dies der Fall, wird die Dienstkontodatei, auf die die Variable verweist, für die Anmeldedaten verwendet.

  2. Wenn die Umgebungsvariable nicht festgelegt ist, verwendet ADC das Standarddienstkonto, das von Compute Engine, Google Kubernetes Engine, App Engine und Cloud Functions für Anwendungen bereitgestellt wird, die für diese Dienste ausgeführt werden.

  3. Wenn die Anmeldedaten weder im ersten noch im zweiten Schritt ermittelt werden können, tritt ein Fehler auf.

Das folgende Admin SDK-Codebeispiel veranschaulicht diese Strategie. In diesem Beispiel werden die Anmeldedaten für die Anwendung nicht explizit angegeben. Sie können aber im Rahmen dieses Vorgehens von ADC implizit ermittelt werden, sofern die Umgebungsvariable festgelegt ist oder die Anwendung in Compute Engine, Google Kubernetes Engine, App Engine oder Cloud Functions ausgeführt wird.

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(),
});

Anmeldedaten manuell angeben

Firebase-Projekte unterstützen Google-Dienstkonten, mit denen Sie Firebase-Server-APIs von Ihrem App-Server oder einer vertrauenswürdigen Umgebung aus aufrufen können. Wenn Sie Code lokal entwickeln oder Ihre Anwendung vor Ort bereitstellen, können Sie Anmeldedaten verwenden, die über dieses Dienstkonto abgerufen wurden, um Serveranfragen zu autorisieren.

Um ein Dienstkonto zu authentifizieren und ihm den Zugriff auf Firebase-Dienste zu gewähren, müssen Sie eine Datei mit dem privaten Schlüssel im JSON-Format generieren.

So erstellen Sie eine Datei mit einem privaten Schlüssel für Ihr Dienstkonto:

  1. Öffnen Sie in der Firebase-Konsole Einstellungen > Dienstkonten.

  2. Klicken Sie auf Neuen privaten Schlüssel generieren und dann auf Schlüssel generieren, um die Aktion zu bestätigen.

  3. Speichern Sie die JSON-Datei mit dem Schlüssel an einem sicheren Ort.

Wenn Sie die Autorisierung über ein Dienstkonto vornehmen, haben Sie zwei Möglichkeiten, die Anmeldedaten für Ihre Anwendung bereitzustellen. Sie können entweder die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen oder den Pfad zum Dienstkontoschlüssel explizit im Code übergeben. Die erste Option ist sicherer und wird dringend empfohlen.

So legen Sie die Umgebungsvariable fest:

Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad der JSON-Datei fest, die Ihren Dienstkontoschlüssel enthält. Diese Variable gilt nur für Ihre aktuelle Shell-Sitzung. Wenn Sie eine neue Sitzung öffnen, müssen Sie die Variable noch einmal festlegen.

Linux oder macOS

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

Windows

Mit PowerShell:

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

Nachdem Sie die oben genannten Schritte ausgeführt haben, können die Standardanmeldedaten für Anwendungen Ihre Anmeldedaten implizit ermitteln. So können Sie Dienstkontoanmeldedaten verwenden, wenn Sie in Nicht-Google-Umgebungen testen oder ausführen.

Anmeldedaten zum Erstellen von Zugriffstokens verwenden

Sofern Sie nicht die Firebase Admin SDK verwenden, die die Autorisierung automatisch übernimmt, müssen Sie das Zugriffstoken erstellen und es zum Senden von Anfragen hinzufügen.

Verwenden Sie Ihre Firebase-Anmeldedaten zusammen mit der Google Auth-Bibliothek für Ihre bevorzugte Sprache, um ein kurzlebiges OAuth 2.0-Zugriffstoken abzurufen:

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

In diesem Beispiel authentifiziert die Google API-Clientbibliothek die Anfrage mit einem JSON-Webtoken (JWT). Weitere Informationen finden Sie unter JSON Web Tokens.

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

Nach Ablauf des Zugriffstokens wird die Methode zum Aktualisieren des Tokens automatisch aufgerufen, um ein aktualisiertes Zugriffstoken abzurufen.

Wenn Sie den Zugriff auf FCM autorisieren möchten, fordern Sie den Bereich https://www.googleapis.com/auth/firebase.messaging an.

Zugriffstoken einem HTTP-Anfrageheader hinzufügen:

Fügen Sie das Token als Wert des Authorization-Headers im Format Authorization: Bearer <access_token> hinzu:

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

Mit einem Dienstkonto aus einem anderen Projekt autorisieren

Sie können Nachrichten für ein Projekt (das „Zielprojekt“) senden und dabei ein OAuth 2.0-Token verwenden, das aus einem Dienstkonto in einem anderen Projekt (dem „Absenderprojekt“) generiert wurde. So können Sie die Verwaltung von Dienstkonten in einem Projekt zentralisieren und gleichzeitig Nachrichten im Namen anderer senden. Gehen Sie dazu so vor:

  1. API aktivieren:Achten Sie darauf, dass die Firebase Cloud Messaging API im Absenderprojekt aktiviert ist.
  2. Dienstkonto erstellen:Erstellen Sie ein Dienstkonto im Senderprojekt.
  3. Berechtigungen erteilen:Weisen Sie im Zielprojekt der E-Mail-Adresse des Dienstkontos auf der IAM-Seite die Rolle Firebase Cloud Messaging API Admin zu. Dadurch kann das Dienstkonto aus dem anderen Projekt Nachrichten an das Zielprojekt senden.
  4. Token abrufen:Generieren Sie ein OAuth 2.0-Zugriffstoken für das Dienstkonto im Absenderprojekt. Dazu haben Sie folgende Möglichkeiten:
    • JSON-Schlüsseldatei des Dienstkontos herunterladen und verwenden.
    • Alternativ können Sie Workload Identity verwenden, wenn Ihr Dienst in Google Cloud ausgeführt wird.
  5. Anfrage senden:Verwenden Sie das abgerufene Zugriffstoken im Authorization-Header Ihrer Send-Anfrage. Die Anfrage muss an den HTTP v1-Endpunkt für das Zielprojekt gesendet werden: 
        POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send

Nachrichten an bestimmte Geräte senden

Wenn Sie die Nachricht an ein einzelnes, bestimmtes Gerät senden möchten, übergeben Sie das Registrierungstoken des Geräts wie unten gezeigt.

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"
      }
   }
}

cURL-Befehl:

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

Bei Erfolg ist die HTTP v1-API-Antwort ein JSON-Objekt mit der Nachrichten-ID:

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

Testbenachrichtigung mit der FCM HTTP v1 API senden

In diesem Abschnitt wird beschrieben, wie Sie mit der FCM HTTP v1 API eine Testbenachrichtigung senden.

HTTP-Anfrage-URL

Die Anfrage besteht aus einem HTTP POST an das angegebene Ziel (ein Registrierungstoken, ein Thema oder eine Bedingung) unter der folgenden URL:

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

Vollständiges JSON-Beispiel für HTTP-Anfrage

Hier ist ein vollständiges Beispiel dafür, wie Sie eine Benachrichtigung in einer HTTP-POST-Anfrage posten:

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

Ausführen

Klicken Sie auf Ausführen, um das Beispiel im API Explorer auszuprobieren.