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 (nur Protokoll)

Sie können Nachrichten mit einer Benachrichtigungsnutzlast aus vordefinierten Feldern, einer Datennutzlast aus eigenen benutzerdefinierten Feldern oder einer Nachricht senden, die beide Arten von Nutzlast enthält. 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 Server anfragen an Firebase-Dienste zu autorisieren:

  • Google-Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC)
  • Eine JSON-Datei für ein 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 ausgeführt wird (einschließlich Cloud Functions for Firebase), verwenden Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC). ADC verwendet Ihr vorhandenes Standarddienst konto, um Anmeldedaten zum Autorisieren von Anfragen abzurufen. Außerdem ermöglicht ADC flexible lokale Tests über die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS. Für die umfassendste Automatisierung des Autorisierungsablaufs verwenden Sie ADC zusammen mit Admin SDK-Serverbibliotheken.

Wenn Ihre Anwendung in einer anderen Serverumgebung als Google ausgeführt wird, müssen Sie eine JSON-Datei für ein Dienstkonto aus Ihrem Firebase-Projekt herunterladen. Solange Sie Zugriff auf ein Dateisystem mit der Datei des privaten Schlüssels 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 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 ADC keine der oben genannten Anmeldedaten verwenden kann, 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. Sie können aber im Rahmen dieses Vorgehens von ADC implizit ermittelt werden, sofern die Umgebungsvariable festgelegt ist, oder sofern 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 bereitstellen

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 Zugriff auf Firebase-Dienste zu gewähren, müssen Sie eine Datei mit einem privaten Schlüssel im JSON Format generieren.

So generieren 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 bestätigen Sie mit Schlüssel generieren.

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

Wenn Sie über ein Dienstkonto autorisieren, haben Sie zwei Möglichkeiten, die Anmeldedaten für Ihre Anwendung bereitzustellen. Sie können entweder die GOOGLE_APPLICATION_CREDENTIALS Umgebungsvariable 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 (Application Default Credentials, ADC) Ihre Anmeldedaten implizit ermitteln. So können Sie Dienst kontoanmeldedaten verwenden, wenn Sie in anderen Umgebungen als Google testen oder ausführen.

Mit Anmeldedaten Zugriffstokens erstellen

Wenn Sie nicht das Firebase Admin SDKverwenden, das die Autorisierung automatisch übernimmt, müssen Sie das Zugriffstoken erstellen und es zu den Sendeanfragen hinzufügen.

Verwenden Sie Ihre Firebase-Anmeldedaten zusammen mit der Google-Authentifizierungsbibliothek 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-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
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 Ihres Zugriffstokens wird die Methode zur Tokenaktualisierung automatisch aufgerufen, um ein aktualisiertes Zugriffstoken abzurufen.

Um den Zugriff auf FCM zu autorisieren, 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
}
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 von 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 Dienst konto im Absenderprojekt.
  3. Berechtigungen gewähren: Gewähren Sie im Zielprojekt der E-Mail-Adresse des Dienstkontos auf der IAM-Seite die Rolle „Firebase Cloud Messaging API Admin“. So 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 Absender projekt. Dazu haben Sie folgende Möglichkeiten:
    • Laden Sie die JSON-Datei des Dienstkontoschlüssels herunter und verwenden Sie sie.
    • 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 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 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 eine Testbenachrichtigung mit der FCM HTTP v1 API senden.

HTTP-Anfrage-URL

Die Anfrage besteht aus einer HTTP-POST-Anfrage an das angegebene Ziel (ein Registrierungstoken, 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 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.