Diese Seite wurde von der Cloud Translation API übersetzt.

Von Legacy-FCM APIs zu HTTP v1 migrieren

Apps, die die verworfenen Legacy-APIs für HTTP und XMPP von FCM verwenden, sollten so bald wie möglich zur HTTP v1 API migrieren. Das Senden von Nachrichten (einschließlich Upstream-Nachrichten) mit diesen APIs wurde am 20. Juni 2023 eingestellt und die Abschaltung beginnt am 22. Juli 2024.

Weitere Informationen zu den betroffenen Funktionen

Neben dem laufenden Support und neuen Funktionen bietet die HTTP v1 API gegenüber den alten APIs folgende Vorteile:

Bessere Sicherheit durch Zugriffstokens: Die HTTP v1 API verwendet kurzlebige Zugriffstokens gemäß dem OAuth2-Sicherheitsmodell. Sollte ein Zugriffstoken öffentlich werden, kann es nur etwa eine Stunde lang missbräuchlich verwendet werden, bevor es abläuft. Aktualisierungstokens werden nicht so oft übertragen wie die Sicherheitsschlüssel, die in der alten API verwendet werden. Daher ist es viel unwahrscheinlicher, dass sie abgefangen werden.
Effizientere Anpassung von Nachrichten auf verschiedenen Plattformen: Für den Nachrichtentext enthält die HTTP v1-API gemeinsame Schlüssel, die an alle Zielinstanzen gesendet werden, sowie plattformspezifische Schlüssel, mit denen Sie die Nachricht auf verschiedenen Plattformen anpassen können. So können Sie „Overrides“ erstellen, mit denen in einer einzelnen Nachricht leicht unterschiedliche Nutzlasten an verschiedene Clientplattformen gesendet werden.
Bessere Erweiterbarkeit und Zukunftsfähigkeit für neue Clientplattformversionen: Die HTTP v1 API unterstützt alle Messaging-Optionen, die auf Apple-Plattformen, Android und im Web verfügbar sind. Da jede Plattform einen eigenen definierten Block in der JSON-Nutzlast hat, kann FCM die API nach Bedarf auf neue Versionen und neue Plattformen ausweiten.

Serverendpunkt aktualisieren

Die Endpunkt-URL für die HTTP v1-API unterscheidet sich in folgenden Punkten vom Legacy-Endpunkt:

Es ist versioniert, mit /v1 im Pfad.
Der Pfad enthält die Projekt-ID des Firebase-Projekts für Ihre App im Format /projects/myproject-ID/. Diese ID ist in der Firebase-Konsole auf dem Tab Allgemeine Projekteinstellungen verfügbar.
Sie gibt die Methode send explizit als :send an.

Wenn Sie den Serverendpunkt für HTTP v1 aktualisieren möchten, fügen Sie diese Elemente dem Endpunkt im Header Ihrer Sendeanfragen hinzu.

HTTP-Anfragen vor

POST https://fcm.googleapis.com/fcm/send

XMPP-Anfragen vor

Alte XMPP-Nachrichten werden über eine Verbindung zum folgenden Endpunkt gesendet:

fcm-xmpp.googleapis.com:5235

Nachher

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

Autorisierung von Sendeanfragen aktualisieren

Anstelle des Server-Schlüssel-Strings, der in Legacy-Anfragen verwendet wurde, ist für HTTP v1-Sendeanfragen ein OAuth 2.0-Zugriffstoken erforderlich. Wenn Sie das Admin SDK zum Senden von Nachrichten verwenden, wird das Token von der Bibliothek verarbeitet. Wenn Sie das Rohprotokoll verwenden, rufen Sie das Token wie in diesem Abschnitt beschrieben ab und fügen Sie es dem Header als Authorization: Bearer <valid Oauth 2.0 token> hinzu.

Vorher

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Nachher

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

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:

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.
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.
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:

Öffnen Sie in der Firebase-Konsole Einstellungen > Dienstkonten.
Klicken Sie auf Neuen privaten Schlüssel generieren und bestätigen Sie die Aktion mit einem Klick auf Schlüssel generieren.
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

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.tokenmessaging.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

Nutzlast von Sendeanfragen aktualisieren

Mit FCM HTTP v1 wird eine wichtige Änderung bei der Strukturierung der JSON-Nachrichtennutzlast eingeführt. In erster Linie sorgen diese Änderungen dafür, dass Nachrichten auf verschiedenen Clientplattformen korrekt verarbeitet werden. Außerdem bieten sie Ihnen zusätzliche Flexibilität, um Nachrichtenfelder pro Plattform anzupassen oder zu überschreiben.

Sehen Sie sich nicht nur die Beispiele in diesem Abschnitt an, sondern lesen Sie auch Nachricht plattformübergreifend anpassen und die API-Referenz, um sich mit HTTP v1 vertraut zu machen.

Beispiel: Einfache Benachrichtigungsnachricht

Hier sehen Sie einen Vergleich einer sehr einfachen Benachrichtigungs-Payload, die nur die Felder title, body und data enthält. Damit werden die grundlegenden Unterschiede zwischen Legacy- und HTTP v1-Payloads veranschaulicht.

Vorher

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

Nachher

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

Beispiel: Verschachtelte JSON-Daten

Im Gegensatz zur alten Messaging API unterstützt die HTTP v1 API keine verschachtelten JSON-Werte im Feld data. Eine Konvertierung von JSON in einen String ist erforderlich.

Vorher

{
  ...
  "data": {
    "keysandvalues": {"key1": "value1", "key2": 123}
  }
}

Nachher

{
  "message": {
   ...
    "data": {
      "keysandvalues": "{\"key1\": \"value1\", \"key2\": 123}"
    }
  }
}

Beispiel: Targeting auf mehrere Plattformen

Bei der alten API wurden Überschreibungen im Backend vorgenommen, um die Ausrichtung auf mehrere Plattformen zu ermöglichen. Im Gegensatz dazu bietet HTTP v1 plattformspezifische Schlüsselblöcke, die alle Unterschiede zwischen den Plattformen explizit und für den Entwickler sichtbar machen. So können Sie mit einer einzigen Anfrage mehrere Plattformen ansprechen, wie im folgenden Beispiel gezeigt.

Vorher

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

Nachher

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

Beispiel: Anpassung mit Plattformüberschreibungen

Die HTTP v1 API vereinfacht nicht nur das plattformübergreifende Ausrichten von Nachrichten, sondern bietet auch die Flexibilität, Nachrichten für jede Plattform anzupassen.

Vorher

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

Nachher

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

Beispiel: Ausrichtung auf bestimmte Geräte

Wenn Sie mit der HTTP v1 API bestimmte Geräte ansprechen möchten, geben Sie im Schlüssel token anstelle des Schlüssels to das aktuelle Registrierungstoken des Geräts an.

Vorher

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

Nachher

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

Weitere Beispiele und Informationen zur FCM HTTP v1 API finden Sie hier:

Anleitung zum Erstellen von App-Server-Anfragen mit der HTTP v1 API. Alle „REST“-Snippets verwenden die v1 API, sofern nicht anders angegeben.
Firebase-Blog

Von Legacy-FCM APIs zu HTTP v1 migrieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Serverendpunkt aktualisieren

HTTP-Anfragen vor

XMPP-Anfragen vor

Nachher

Autorisierung von Sendeanfragen aktualisieren

Vorher

Nachher

Anmeldedaten mit ADC bereitstellen

Node.js

Java

Python

Go

C#

Anmeldedaten manuell angeben

Linux oder macOS

Windows

Anmeldedaten zum Erstellen von Zugriffstokens verwenden

Node.js

Python

Java

Node.js

Python

Java

Nutzlast von Sendeanfragen aktualisieren

Beispiel: Einfache Benachrichtigungsnachricht

Vorher

Nachher

Beispiel: Verschachtelte JSON-Daten

Vorher

Nachher

Beispiel: Targeting auf mehrere Plattformen

Vorher

Nachher

Beispiel: Anpassung mit Plattformüberschreibungen

Vorher

Nachher

Beispiel: Ausrichtung auf bestimmte Geräte

Vorher

Nachher

Von Legacy-FCM APIs zu HTTP v1 migrieren