Migrieren Sie von älteren FCM-APIs auf HTTP v1

Apps, die die veralteten FCM-Legacy-APIs für HTTP und XMPP verwenden, sollten zum frühestmöglichen Zeitpunkt auf die HTTP v1-API migrieren. Das Senden von Nachrichten (einschließlich Upstream-Nachrichten) mit diesen APIs wurde am 20. Juni 2023 eingestellt und wird im Juni 2024 entfernt .

Neben fortlaufender Unterstützung und neuen Funktionen bietet die HTTP v1-API folgende Vorteile gegenüber den Legacy-APIs:

  • Höhere Sicherheit durch Zugriffstoken Die HTTP v1-API verwendet kurzlebige Zugriffstoken gemäß dem OAuth2-Sicherheitsmodell. Falls ein Zugriffstoken öffentlich wird, kann es nur etwa eine Stunde lang böswillig verwendet werden, bevor es abläuft. Aktualisierungstoken werden nicht so oft übertragen wie die in der Legacy-API verwendeten Sicherheitsschlüssel, sodass die Wahrscheinlichkeit, dass sie erfasst werden, deutlich geringer ist.

  • Effizientere plattformübergreifende Anpassung von Nachrichten Für den Nachrichtentext verfügt die HTTP v1-API über gemeinsame Schlüssel, die an alle Zielinstanzen gehen, sowie plattformspezifische Schlüssel, mit denen Sie die Nachricht plattformübergreifend anpassen können. Auf diese Weise können Sie „Überschreibungen“ erstellen, die in einer einzigen Nachricht leicht unterschiedliche Nutzlasten an verschiedene Client-Plattformen senden.

  • Erweiterbarer und zukunftssicherer für neue Client-Plattformversionen. Die HTTP v1-API unterstützt vollständig die auf Apple-Plattformen, Android und Web verfügbaren Messaging-Optionen. Da jede Plattform über einen eigenen definierten Block in der JSON-Nutzlast verfügt, kann FCM die API bei Bedarf auf neue Versionen und neue Plattformen erweitern.

Aktualisieren Sie den Serverendpunkt

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 auf der Registerkarte „Allgemeine Projekteinstellungen“ der Firebase-Konsole verfügbar.
  • Es gibt explizit an, dass die send als :send angegeben werden soll.

Um den Serverendpunkt für HTTP v1 zu aktualisieren, fügen Sie diese Elemente zum Endpunkt im Header Ihrer Sendeanfragen hinzu.

HTTP-Anfragen vorher

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

XMPP-Anfragen vorher

Ältere XMPP-Nachrichten werden über eine Verbindung an den folgenden Endpunkt gesendet:

fcm-xmpp.googleapis.com:5235

Nach

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

Autorisierung von Sendeanfragen aktualisieren

Anstelle der in Legacy-Anfragen verwendeten Serverschlüsselzeichenfolge erfordern HTTP v1-Sendeanfragen ein OAuth 2.0-Zugriffstoken. Wenn Sie das Admin SDK zum Senden von Nachrichten verwenden, verwaltet die Bibliothek das Token für Sie. 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.

Vor

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

Nach

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

Abhängig von den Details Ihrer Serverumgebung verwenden Sie eine Kombination dieser Strategien, um Serveranfragen an Firebase-Dienste zu autorisieren:

  • Standardanmeldeinformationen für Google-Anwendungen (ADC)
  • Eine JSON-Datei für ein Dienstkonto
  • Ein kurzlebiges OAuth 2.0-Zugriffstoken, das von einem Dienstkonto abgeleitet ist

Wenn Ihre Anwendung auf Compute Engine, Google Kubernetes Engine, App Engine oder Cloud Functions (einschließlich Cloud Functions für Firebase) ausgeführt wird , verwenden Sie Application Default Credentials (ADC). ADC verwendet Ihr vorhandenes Standarddienstkonto, um Anmeldeinformationen zum Autorisieren von Anforderungen abzurufen, und ADC ermöglicht flexible lokale Tests über die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS . Für die vollständigste Automatisierung des Autorisierungsablaufs verwenden Sie ADC zusammen mit Admin SDK-Serverbibliotheken.

Wenn Ihre Anwendung in einer Nicht-Google-Serverumgebung ausgeführt wird , müssen Sie eine JSON-Datei für ein Dienstkonto aus Ihrem Firebase-Projekt herunterladen. Solange Sie Zugriff auf ein Dateisystem haben, das die private Schlüsseldatei enthält, können Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS verwenden, um Anfragen mit diesen manuell erhaltenen Anmeldeinformationen 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 Anmeldeinformationen preisgegeben werden.

Geben Sie Anmeldeinformationen mithilfe von ADC an

Google Application Default Credentials (ADC) prüft Ihre Anmeldeinformationen in der folgenden Reihenfolge:

  1. ADC prüft, ob die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS gesetzt ist. Wenn die Variable festgelegt ist, verwendet ADC die Dienstkontodatei, auf die die Variable verweist.

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

  3. Wenn ADC keine der oben genannten Anmeldeinformationen verwenden kann, gibt das System einen Fehler aus.

Das folgende Admin SDK-Codebeispiel veranschaulicht diese Strategie. Im Beispiel werden die Anmeldeinformationen der Anwendung nicht explizit angegeben. ADC ist jedoch in der Lage, die Anmeldeinformationen implizit zu finden, solange die Umgebungsvariable festgelegt ist oder die Anwendung auf 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()

Gehen

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

Geben Sie die Anmeldeinformationen manuell ein

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

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

So generieren Sie eine private Schlüsseldatei 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 dann, indem Sie auf „Schlüssel generieren“ klicken.

  3. Speichern Sie die JSON-Datei, die den Schlüssel enthält, sicher.

Bei der Autorisierung über ein Dienstkonto haben Sie zwei Möglichkeiten, die Anmeldeinformationen 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 Dateipfad der JSON-Datei fest, die Ihren Dienstkontoschlüssel enthält. Diese Variable gilt nur für Ihre aktuelle Shell-Sitzung. Wenn Sie also eine neue Sitzung öffnen, legen Sie die Variable erneut fest.

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, kann Application Default Credentials (ADC) Ihre Anmeldeinformationen implizit ermitteln, sodass Sie beim Testen oder Ausführen in Nicht-Google-Umgebungen Dienstkonto-Anmeldeinformationen verwenden können.

Verwenden Sie Anmeldeinformationen, um Zugriffstoken zu erstellen

Verwenden Sie Ihre Firebase-Anmeldeinformationen 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 oder 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

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

Nachdem Ihr Zugriffstoken abgelaufen ist, wird die Token-Aktualisierungsmethode 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-Anforderungsheader hinzu:

Fügen Sie das Token als Wert des Authorization Headers 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;

Aktualisieren Sie die Nutzlast von Sendeanfragen

FCM HTTP v1 führt eine wesentliche Änderung in der Strukturierung der JSON-Nachrichtennutzlast ein. Diese Änderungen stellen in erster Linie sicher, dass Nachrichten korrekt verarbeitet werden, wenn sie auf verschiedenen Client-Plattformen empfangen werden. Darüber hinaus bieten Ihnen die Änderungen zusätzliche Flexibilität beim Anpassen oder „Überschreiben“ von Nachrichtenfeldern pro Plattform.

Sehen Sie sich nicht nur die Beispiele in diesem Abschnitt an, sondern lesen Sie auch „Anpassen einer Nachricht auf verschiedenen Plattformen“ und lesen Sie die API-Referenz , um sich mit HTTP v1 vertraut zu machen.

Beispiel: einfache Benachrichtigungsnachricht

Hier ist ein Vergleich einer sehr einfachen Benachrichtigungsnutzlast – die nur title , body und data enthält – und zeigt die grundlegenden Unterschiede zwischen Legacy- und HTTP v1-Nutzlasten.

Vor

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

Nach

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

Beispiel: Ausrichtung auf mehrere Plattformen

Um das Targeting auf mehreren Plattformen zu ermöglichen, führte die Legacy-API Überschreibungen im Backend durch. Im Gegensatz dazu stellt HTTP v1 plattformspezifische Schlüsselblöcke bereit, die alle Unterschiede zwischen Plattformen explizit und für den Entwickler sichtbar machen. Dadurch können Sie mit einer einzigen Anfrage immer mehrere Plattformen ansprechen, wie im folgenden Beispiel gezeigt.

Vor

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

Nach

{
  "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: Anpassen mit Plattformüberschreibungen

Die HTTP v1-API vereinfacht nicht nur das plattformübergreifende Targeting von Nachrichten, sondern bietet auch die Flexibilität, Nachrichten pro Plattform anzupassen.

Vor

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

Nach

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

Um bestimmte Geräte mit der HTTP v1-API anzusprechen, geben Sie das aktuelle Registrierungstoken des Geräts im token Schlüssel anstelle des to Schlüssels an.

Vor

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

Nach

{
   "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: