Firebase is back at Google I/O on May 10! Register now

Migrieren Sie von Legacy-HTTP zu HTTP v1

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Apps, die die ältere HTTP-API von FCM verwenden, sollten die Migration zur HTTP v1-API anhand der Anweisungen in diesem Handbuch in Erwägung ziehen. Die HTTP v1-API hat diese Vorteile gegenüber der Legacy-API:

  • Bessere 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 Sicherheitsschlüssel, die in der Legacy-API verwendet werden, daher ist es viel unwahrscheinlicher, dass sie erfasst werden.

  • 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 leicht unterschiedliche Payloads in einer einzigen Nachricht an verschiedene Client-Plattformen senden.

  • Erweiterbarer und zukunftssicherer für neue Client-Plattformversionen Die HTTP v1 API unterstützt vollständig Messaging-Optionen, die auf Apple-Plattformen, Android und Web verfügbar sind. Da jede Plattform ihren eigenen definierten Block in der JSON-Nutzlast hat, kann FCM die API nach 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 die send als :send .

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

Vor

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

Nach

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

Autorisierung von Sendeaufträgen aktualisieren

Anstelle der Serverschlüsselzeichenfolge, die in Legacy-Anforderungen verwendet wird, erfordern HTTP v1-Sendeanforderungen ein OAuth 2.0-Zugriffstoken. Wenn Sie das Admin SDK zum Senden von Nachrichten verwenden, verarbeitet die Bibliothek das Token für Sie. Wenn Sie das Raw-Protokoll 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

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

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

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 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 . Verwenden Sie für die vollständigste Automatisierung des Autorisierungsflusses ADC zusammen mit Admin SDK-Serverbibliotheken.

Wenn Ihre Anwendung in einer Nicht-Google-Serverumgebung ausgeführt wird , müssen Sie eine Dienstkonto-JSON-Datei 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 – was aufgrund des Risikos, dass Ihre Anmeldeinformationen preisgegeben werden, mit äußerster Sorgfalt erfolgen sollte.

Geben Sie Anmeldeinformationen mit ADC an

Google Application Default Credentials (ADC) prüft Ihre Anmeldedaten 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. Das Beispiel gibt die Anwendungsanmeldeinformationen nicht explizit an. ADC kann die Anmeldedaten jedoch implizit finden, solange die Umgebungsvariable festgelegt ist oder solange 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)
}
init.go

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 aufrufen können. Wenn Sie Code lokal entwickeln oder Ihre Anwendung lokal bereitstellen, können Sie Anmeldeinformationen verwenden, die Sie über dieses Dienstkonto erhalten haben, um Serveranforderungen zu autorisieren.

Um ein Dienstkonto zu authentifizieren und 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 mit dem Schlüssel 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 Schlüssel des Dienstkontos 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 obigen Schritte ausgeführt haben, kann Application Default Credentials (ADC) Ihre Anmeldedaten implizit bestimmen, sodass Sie beim Testen oder Ausführen in Nicht-Google-Umgebungen Dienstkonto-Anmeldedaten verwenden können.

Verwenden Sie Anmeldeinformationen, um Zugriffstoken zu prä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-Web-Token oder JWT. Weitere Informationen finden Sie unter JSON-Webtoken .

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.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
Messaging.java

Nachdem Ihr Zugriffstoken abgelaufen ist, wird die Tokenaktualisierungsmethode 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 zu 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
}
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 " + getAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;
Messaging.java

Aktualisieren Sie die Nutzlast von Sendeanforderungen

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

Sehen Sie sich neben den Beispielen in diesem Abschnitt auch eine plattformübergreifende Nachricht anpassen und die API-Referenz an, 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, hat die Legacy-API Überschreibungen im Back-End durchgeführt. Im Gegensatz dazu bietet HTTP v1 plattformspezifische Schlüsselblöcke, die alle Unterschiede zwischen den Plattformen explizit und für den Entwickler sichtbar machen. Auf diese Weise können Sie immer mehrere Plattformen mit einer einzigen Anfrage 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: Customizing mit Plattform-Overrides

Neben der Vereinfachung des plattformübergreifenden Targetings von Nachrichten bietet die HTTP v1-API 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 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 im Firebase-Blog .