Serverreferenz

Stay organized with collections Save and categorize content based on your preferences.

Die Serverimplementierung ist optional. Verwenden Sie den Instanz-ID-Dienst, wenn Sie diese Vorgänge ausführen möchten:

Informationen zu Anwendungsinstanzen abrufen

Rufen Sie den Instanz-ID-Dienst an diesem Endpunkt auf und geben Sie das Token der App-Instanz an, um Informationen zu einer Anwendungsinstanz abzurufen:

 https://iid.googleapis.com/iid/info/IID_TOKEN

Parameter

  • Authorization: Schlüssel=YOUR_API_KEY. Legen Sie diesen Parameter im Header fest.
  • [optional] Boolescher Wert details: Legen Sie diesen Abfrageparameter auf true fest, um Aboinformationen für FCM oder GCM-Themen (falls vorhanden) abzurufen, die mit diesem Token verknüpft sind. Wenn keine Angabe erfolgt, wird standardmäßig false verwendet.

Ergebnisse

Bei Erfolg gibt der Aufruf den HTTP-Status 200 und ein JSON-Objekt zurück, das Folgendes enthält:

  • application: Paketname, der dem Token zugeordnet ist.
  • authorizedEntity: Projekt-ID, die zum Senden an das Token autorisiert ist.
  • applicationVersion: Version der Anwendung.
  • appSignersha1 Fingerabdruck für die auf das Paket angewendete Signatur. Gibt an, welche Partei die App signiert hat, z. B. Play Store.
  • platform: Gibt ANDROID, IOS oder CHROME zurück, um die Geräteplattform anzugeben, zu der das Token gehört.

Wenn das Flag details festgelegt ist:

  • rel – Beziehungen, die dem Token zugeordnet sind. Zum Beispiel eine Liste von Themenabos.

Beispiel für eine GET-Anfrage

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Beispielergebnis

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "appSigner":"1a2bc3d4e5"
  "rel":{
    "topics":{
      "topicname1":{"addDate":"2015-07-30"},
      "topicname2":{"addDate":"2015-07-30"},
      "topicname3":{"addDate":"2015-07-30"},
      "topicname4":{"addDate":"2015-07-30"}
    }
  }
}

Beziehungszuordnungen für App-Instanzen erstellen

Mit der Instance ID API können Sie Beziehungszuordnungen für App-Instanzen erstellen. Sie können beispielsweise einem Google Cloud Messaging-Thema ein Registrierungstoken zuordnen und die App-Instanz dem Thema abonnieren. Die API bietet Methoden, um solche Beziehungen einzeln oder im Bulk zu erstellen.

Beziehungszuordnung für eine Anwendungsinstanz erstellen

Mit einem Registrierungstoken und einer unterstützten Beziehung können Sie eine Zuordnung erstellen. Sie können beispielsweise eine App-Instanz für ein Google Cloud Messaging-Thema abonnieren. Dazu rufen Sie den Instanz-ID-Dienst an diesem Endpunkt auf und geben das Token der App-Instanz so an:

 https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME

Parameter

  • Authorization: Schlüssel=YOUR_API_KEY. Legen Sie diesen Parameter im Header fest.

Ergebnisse

Bei Erfolg gibt der Aufruf den HTTP-Status 200 zurück.

Beispiel für eine POST-Anfrage

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Beispielergebnis

HTTP 200 OK
{}

Beziehungszuordnungen für mehrere App-Instanzen verwalten

Mit den Batchmethoden des Instanz-ID-Dienstes können Sie Anwendungsinstanzen im Batch verwalten. Sie können beispielsweise App-Instanzen im Bulk zu einem FCM- oder GCM-Thema hinzufügen oder entfernen. Rufen Sie zum Aktualisieren von bis zu 1.000 App-Instanzen pro API-Aufruf den Instanz-ID-Dienst an diesem Endpunkt auf und geben Sie im JSON-Text die App-Instanztokens an:

 https://iid.googleapis.com/iid/v1:batchAdd

 https://iid.googleapis.com/iid/v1:batchRemove

Parameter

  • Authorization: Schlüssel=YOUR_API_KEY. Legen Sie diesen Parameter im Header fest.
  • to : der Name des Themas
  • registration_tokens: Das Array der IID-Tokens für die Anwendungsinstanzen, die Sie hinzufügen oder entfernen möchten.

Ergebnisse

Bei Erfolg gibt der Aufruf den HTTP-Status 200 zurück. Leere Ergebnisse zeigen an, dass das Token erfolgreich abonniert wurde. Für fehlgeschlagene Abos enthält das Ergebnis einen der folgenden Fehlercodes:

  • NOT_FOUND : Das Registrierungstoken wurde gelöscht oder die App wurde deinstalliert.
  • INVALID_ARGUMENT: Das angegebene Registrierungstoken ist für die Sender-ID nicht gültig.
  • INTERNAL: Der Back-End-Server ist aus unbekannten Gründen fehlgeschlagen. Wiederholen Sie die Anfrage.
  • TOO_MANY_TOPICS – Übermäßig viele Themen pro App-Instanz.
  • RESOURCE_EXHAUSTED: Zu viele Abo- oder Kündigungsanfragen innerhalb kurzer Zeit. Wiederholen Sie den Vorgang mit exponentiellem Backoff.

Beispiel für eine POST-Anfrage

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
   "to": "/topics/movies",
   "registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}

Beispielergebnis

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

Registrierungstokens für APNs-Tokens erstellen

Mit der Methode batchImport des Instanz-ID-Dienstes können Sie vorhandene iOS-APNs-Tokens im Bulk in Google Cloud Messaging oder Firebase Cloud Messaging importieren und sie gültigen Registrierungstokens zuordnen. Rufen Sie den Instanz-ID-Dienst an diesem Endpunkt auf und stellen Sie im JSON-Text eine Liste der APNs-Tokens bereit:

 https://iid.googleapis.com/iid/v1:batchImport

Der Antworttext enthält ein Array mit Instanz-ID-Registrierungstokens, die zum Senden von FCM- oder GCM-Nachrichten an das entsprechende APNs-Gerätetoken verwendet werden können.

Parameter

  • Authorization: Schlüssel=YOUR_API_KEY. Legen Sie diesen Parameter im Header fest.
  • application: Bundle-ID der App.
  • sandbox: Boolescher Wert für die Sandbox-Umgebung (TRUE) oder die Produktionsumgebung (FALSE)
  • apns_tokens: Das Array der APNs-Tokens für die Anwendungsinstanzen, die Sie hinzufügen oder entfernen möchten. Maximal 100 Tokens pro Anfrage.

Ergebnisse

Bei Erfolg gibt der Aufruf den HTTP-Status 200 und einen JSON-Ergebnistext zurück. Für jedes in der Anfrage angegebene APN-Token enthält die Ergebnisliste Folgendes:

  • Das APNs-Token.
  • Status. Entweder „OK“ oder eine Fehlermeldung, in der der Fehler beschrieben wird.
  • Für erfolgreiche Ergebnisse das Registrierungstoken, das FCM oder GCM dem APNs-Token zugeordnet ist.

Beispiel für eine POST-Anfrage

https://iid.googleapis.com/iid/v1:batchImport
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
  }
}

Beispielergebnis

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

Registrierungstokens für Push-Abos verwalten

Mit den Webmethoden des Instanz-ID-Dienstes können Sie vorhandene Push-Abos für Firebase Cloud Messaging importieren. Sie können sie auch aktualisieren und löschen.

Wenn Sie ein Push-Abo importieren, erhalten Sie ein Registrierungstoken. Mit diesem Token können Sie FCM-Features wie Messaging zu Themen und Gerätegruppen verwenden, um Benachrichtigungen auf Ihre Webanwendungen auszurichten.

Push-Abos importieren

Sie können Push-Abos über den Web-Endpunkt von InstanceID importieren:

 https://iid.googleapis.com/v1/web/iid

Die Anfrage muss einen Autorisierungsheader enthalten, der auf ein OAuth 2.0-Zugriffstoken, einen kryptografischen Schlüsselheader für Ihren Anwendungsserverserver und das PushSubscription-Objekt im Anfragetext festgelegt ist.

Der Antworttext enthält ein Registrierungstoken, das zum Senden von FCM- oder GCM-Nachrichten an die entsprechende Web-App-Instanz verwendet werden kann, ohne dass die Nutzlast verschlüsselt werden muss.

VAPID-Schlüsselpaar in die Konsole hochladen

Zum Importieren von Schlüsseln benötigen Sie Zugriff auf Inhaberebene für das Firebase-Projekt. Importieren Sie Ihren vorhandenen öffentlichen und privaten Schlüssel in der base64-URL-verschlüsselten Form:

  1. Öffnen Sie in der Firebase Console im Bereich Einstellungen den Tab Cloud Messaging und scrollen Sie zum Abschnitt Webkonfiguration.
  2. Suchen Sie auf dem Tab Web-Push-Zertifikate den Linktext „Vorhandenes Schlüsselpaar importieren“ und wählen Sie ihn aus.
  3. Geben Sie im Dialogfeld Schlüsselpaar importieren Ihre öffentlichen und privaten Schlüssel in die entsprechenden Felder ein und klicken Sie auf Importieren. In der Konsole werden der öffentliche Schlüsselstring und das Datum der Hinzufügung angezeigt.

OAuth2-Token abrufen: Verwenden Sie Anmeldedaten, um Zugriffstoken zu erstellen.

Um ein Zugriffstoken für die Anfrage zu erstellen, müssen Sie das Zugriffstoken erstellen und der HTTP-Anfrage hinzufügen.

Node.js

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token

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

Fordern Sie den Bereich https://www.googleapis.com/auth/firebase.messaging an, um den Zugriff auf FCM zu autorisieren.

Parameter

  • Autorisierung: Bearer <access_token>. Legen Sie diesen Parameter im Header fest.
  • Kryptoschlüssel: p256ecdsa=APPLICATION_PUBLIC_KEY. Legen Sie diesen Parameter im Header fest.
  • Anfragetext: PushSubscription.toJson(). Übergib das Push-Abo an den HTTP-Body, ohne es zu parst. Der Inhalt entspricht der W3C-Codierung von PushSubscription.

Antwort

Bei Erfolg gibt der Aufruf den HTTP-Status 200 OK und einen JSON-Ergebnistext mit dem IID-Token zurück.

Beispiel für eine POST-Anfrage

 https://iid.googleapis.com/v1/web/iid
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

Beispielergebnis

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Push-Abos aktualisieren

Sie können das mit Ihrem Registrierungstoken verknüpfte Push-Abo über den folgenden Endpunkt aktualisieren:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh

Parameter

  • Autorisierung: Bearer <access_token>. Legen Sie diesen Parameter im Header fest.
  • Kryptoschlüssel: p256ecdsa=APPLICATION_PUBLIC_KEY. Legen Sie diesen Parameter im Header fest.
  • Anfragetext: PushSubscription.toJson(). Übergib das Push-Abo an den HTTP-Body, ohne es zu parst. Der Inhalt entspricht der W3C-Codierung von PushSubscription.

Ergebnisse

Bei Erfolg gibt der Aufruf den HTTP-Status 200 und ein Registrierungstoken zurück. Dies kann das Token sein, das Sie in der Anfrage übergeben haben, oder ein neues Token.

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Beispiel für eine POST-Anfrage

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q"",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

Beispielergebnis

 HTTP 200 OK
 {
  "token":"KctODamlM4:CI2k_HHw...3P1"
 }

Push-Abos löschen

Eine DELETE-Anfrage entfernt die Push-Abodetails aus der FCM-Datenbank. Über das Push API-Protokoll können Sie weiterhin Nachrichten in Ihrer Webanwendung empfangen.

Senden Sie zum Löschen eines Push-Abos eine DELETE-Anfrage an:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN

Beispiel für eine DELETE-Anfrage

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

Beispielergebnis

 HTTP 200 OK {}

Fehlerantworten

Aufrufe an die Instanz-ID-Server-API geben die folgenden HTTP-Fehlercodes zurück:

  • HTTP status 400 (Bad request): Anfrageparameter fehlen oder sind ungültig. Weitere Informationen finden Sie in den Fehlermeldungen.
  • HTTP status 401 (Unauthorized): Der Autorisierungsheader ist ungültig.
  • HTTP status 403 (Forbidden) – Autorisierungsheader stimmt nicht mit authorizedEntity überein.
  • HTTP status 404 (Not found): Ungültiger HTTP-Pfad oder ungültiges IID-Token. Weitere Informationen finden Sie in den Fehlermeldungen.
  • HTTP status 503 (Service unavailable): Der Dienst ist nicht verfügbar. Wiederholen Sie die Anfrage mit exponentiellem Backoff.