Nachricht mit der FCM HTTP v1 API senden

Mit der FCM HTTP v1 API können Sie Nachrichtenanfragen erstellen und an die folgenden Zieltypen senden:

  • Name des Themas
  • Bedingung
  • Geräteregistrierungstoken
  • Name der Gerätegruppe (eingestellt, wird am 29. September 2027 entfernt)

Sie können Nachrichten mit einer Benachrichtigungs-Nutzlast aus vordefinierten Feldern, einer Daten-Nutzlast aus Ihren eigenen 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 können Sie eine Kombination dieser Strategien verwenden, um Serveranfragen an Firebase-Dienste zu autorisieren:

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

Wenn Ihre Anwendung in 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. Für eine möglichst vollständige Automatisierung des Autorisierungsablaufs sollten Sie ADC zusammen mit Admin SDK-Serverbibliotheken verwenden.

Wenn Ihre Anwendung in einer Serverumgebung ausgeführt wird, die nicht von Google stammt, müssen Sie eine JSON-Datei für das Dienstkonto aus Ihrem Firebase-Projekt herunterladen. Solange Sie Zugriff auf ein Dateisystem mit der privaten Schlüsseldatei 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 die Dienstkontodatei in Ihrem Code referenzieren. Dies sollte aufgrund des Risikos, dass Ihre Anmeldedaten offengelegt werden, mit äußerster Vorsicht erfolgen.

Anmeldedaten mit Standardanmeldedaten für Anwendungen bereitstellen

Die Standardanmeldedaten für Google-Anwendungen (Application Default Credentials, ADC) prüfen Ihre Anmeldedaten in der folgenden Reihenfolge:

  1. Die Standardanmeldedaten für Anwendungen prüfen, ob die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festgelegt ist. Wenn die Variable festgelegt ist, verwendet ADC die Dienstkontodatei, auf die die Variable verweist.

  2. Wenn die Umgebungsvariable nicht festgelegt ist, verwenden die Standardanmeldedaten für Anwendungen das Standarddienstkonto, das Compute Engine, Google Kubernetes Engine, App Engine und Cloud Functions für Anwendungen bereitstellen, die in diesen Diensten ausgeführt werden.

  3. Wenn die Standardanmeldedaten für Anwendungen keine der oben genannten Anmeldedaten verwenden können, gibt das System einen Fehler aus.

Das folgende Admin SDK-Codebeispiel veranschaulicht diese Strategie. In diesem Beispiel werden die Anmeldedaten für die Anwendung nicht explizit angegeben. ADC kann die Anmeldedaten jedoch implizit finden, solange 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)
}

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 Anwendungsserver oder Ihrer vertrauenswürdigen Umgebung aus aufrufen können. Wenn Sie Code lokal entwickeln oder Ihre Anwendung lokal bereitstellen, können Sie mit den Anmeldedaten, die Sie mit diesem Dienstkonto erhalten, Serveranfragen autorisieren.

Sie können alle Dienstkonten für Ihr Firebase-Projekt auf dem Tab Einstellungen > Dienstkonten aufrufen.

Wenn Sie ein Dienstkonto authentifizieren und für den Zugriff auf Firebase-Dienste autorisieren möchten, müssen Sie eine private Schlüsseldatei im JSON-Format generieren.

So generieren Sie eine private Schlüsseldatei für Ihr Dienstkonto:

  1. Rufen Sie in der Firebase-Konsole die Seite Einstellungen > Tab Dienstkonten auf.

  2. Klicken Sie auf Neuen privaten Schlüssel generieren und bestätigen Sie mit Schlüssel generieren.

  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 für die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS den Dateipfad 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 (Application Default Credentials, ADC) Ihre Anmeldedaten implizit ermitteln. So können Sie Dienstkonto-Anmeldedaten verwenden, wenn Sie in Nicht-Google-Umgebungen testen oder ausführen.

Anmeldedaten zum Erstellen von Zugriffstokens verwenden

Wenn 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 Library 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);
    });
  });
}

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

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

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

Nach Ablauf des Zugriffstokens wird die Methode zur Tokenaktualisierung 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.

So fügen Sie das Zugriffstoken einem HTTP-Anfrageheader hinzu:

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

Node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

Python

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

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;

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 von einem Dienstkonto in einem anderen Projekt, dem „Senderprojekt“, generiert wurde. So können Sie die Dienstkontoverwaltung in einem Projekt zentralisieren und gleichzeitig Nachrichten im Namen anderer senden. Gehen Sie dazu so vor:

  1. Achten Sie darauf, dass die Firebase Cloud Messaging API im Senderprojekt aktiviert ist. Prüfen Sie in der Firebase-Konsole unter Einstellungen > Allgemein, ob die Funktion aktiviert ist. Klicken Sie dann auf den Tab Cloud Messaging.

  2. Erstellen Sie im Absenderprojekt ein Dienstkonto.

  3. Weisen Sie im Zielprojekt der E-Mail-Adresse des Dienstkontos die Rolle Firebase Cloud Messaging API Admin zu. Dies tun Sie in der Google Cloud Console auf der Seite IAM & Verwaltung > IAM. Mit dieser Rolle kann das Dienstkonto aus dem Absenderprojekt Nachrichten an das Zielprojekt senden.

  4. Generieren Sie ein OAuth 2.0-Zugriffstoken für das Dienstkonto im Senderprojekt. Dazu haben Sie folgende Möglichkeiten:

    • Laden Sie die JSON-Datei mit dem Dienstkontoschlüssel herunter und verwenden Sie sie.
    • Workload Identity, wenn Ihr Dienst in Google Cloud ausgeführt wird.

  5. Verwenden Sie das erhaltene Zugriffstoken im Authorization-Header Ihrer Sendeanfrage. 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 eine Nachricht an ein einzelnes, bestimmtes Gerät senden möchten, übergeben Sie das Registrierungstoken des Geräts wie 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 Antwort der HTTP v1 API ein JSON-Objekt, das die Nachrichten-ID enthält:

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

Testbenachrichtigung mit der FCM HTTP v1 API senden

In diesem Abschnitt wird beschrieben, wie Sie eine Testbenachrichtigung mit der FCM HTTP v1 API 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 eine HTTP-Anfrage

Hier ist ein vollständiges Beispiel, das zeigt, wie eine Benachrichtigung in einer HTTP-POST-Anfrage gepostet wird:

{
  "message": {
    "token": REGISTRATION_TOKEN,
    "notification": {
      "title": "FCM API test",
      "body": "This is the body of the notification.",
      "image": "https://firebase.google.com/static/images/products/cloud-messaging/cloud-messaging-hero_1x.png"
    }
  }
}

Ausführen

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