Serverreferenz

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

Informationen zu App-Instanzen abrufen

Wenn Sie Informationen zu einer App-Instanz abrufen möchten, rufen Sie den Dienst „Instanz-ID“ an diesem Endpunkt auf und geben Sie das Token der App-Instanz wie unten gezeigt an:

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

Parameter

  • Authorization: Bearer <access_token>: Legen Sie diesen Parameter im Header fest. Fügen Sie ein kurzlebiges OAuth 2.0-Token als Wert des Headers Authorization hinzu. Weitere Informationen zum Abrufen dieses Tokens finden Sie unter Anmeldedaten manuell bereitstellen.
  • access_token_auth: true: Legen Sie diesen Parameter im Header fest.
  • [Optional] Boolescher Wert details: Setzen Sie diesen Abfrageparameter auf true, um Informationen zu FCM- Themenabos (falls vorhanden) abzurufen, die mit diesem Token verknüpft sind. Wenn nicht angegeben, wird standardmäßig false verwendet.

Ergebnisse

Bei Erfolg gibt der Aufruf den HTTP-Status 200 und ein JSON-Objekt mit folgenden Informationen zurück:

  • application: Der Paketname, der mit dem Token verknüpft ist.
  • authorizedEntity – Die Projekt-ID, die zum Senden an das Token autorisiert ist.
  • applicationVersion: Die Version der Anwendung.
  • platform – gibt ANDROID, IOS oder CHROME zurück, um die Geräte plattform anzugeben, zu der das Token gehört.

Wenn das Flag details festgelegt ist:

  • rel – Die Beziehungen, die mit dem Token verknüpft sind. Beispielsweise eine Liste von Themenabos.

Beispiel für eine GET-Anfrage

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

Beispielergebnis

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

Beziehungskarten für App-Instanzen erstellen

Mit der Instance ID API können Sie Beziehungskarten für App-Instanzen erstellen. Sie können beispielsweise ein Registrierungstoken einem FCM-Thema zuordnen und die App-Instanz für das Thema abonnieren. Die API bietet Methoden zum Erstellen solcher Beziehungen sowohl einzeln als auch im Bulk.

Beziehungszuordnung für eine App-Instanz erstellen

Sie können eine Zuordnung erstellen, wenn Sie ein Registrierungstoken und eine unterstützte Beziehung haben. Sie können beispielsweise eine App-Instanz für ein FCM-Thema abonnieren, indem Sie den Dienst „Instanz-ID“ an diesem Endpunkt aufrufen und das Token der App-Instanz wie unten gezeigt angeben:

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

Parameter

  • Authorization: Bearer <access_token>: Legen Sie diesen Parameter im Header fest. Fügen Sie ein kurzlebiges OAuth 2.0-Token als Wert des Headers Authorization hinzu. Weitere Informationen zum Abrufen dieses Tokens finden Sie unter Anmeldedaten manuell bereitstellen.
  • access_token_auth: true: 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: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

Beispielergebnis

HTTP 200 OK
{}

Beziehungskarten für mehrere App-Instanzen verwalten

Mit den Batch-Methoden des Dienstes „Instanz-ID“ können Sie App-Instanzen im Batch verwalten. Sie können beispielsweise App-Instanzen im Bulk zu einem FCM-Thema hinzufügen oder daraus entfernen. Wenn Sie bis zu 1.000 App-Instanzen pro API-Aufruf aktualisieren möchten, rufen Sie den Dienst „Instanz-ID“ an diesem Endpunkt auf und geben Sie die App-Instanz-Tokens im JSON-Text an:

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

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

Parameter

  • Authorization: Bearer <access_token>: Legen Sie diesen Parameter im Header fest. Fügen Sie ein kurzlebiges OAuth 2.0-Token als Wert des Headers Authorization hinzu. Weitere Informationen zum Abrufen dieses Tokens finden Sie unter Anmeldedaten manuell bereitstellen.
  • access_token_auth: true: Legen Sie diesen Parameter im Header fest.
  • to : Der Themenname.
  • registration_tokens : Das Array von IID-Tokens für die App-Instanzen, die Sie hinzufügen oder entfernen möchten.

Ergebnisse

Bei Erfolg gibt der Aufruf den HTTP-Status 200 zurück. Leere Ergebnisse deuten auf ein erfolgreiches Abo für das Token hin. Bei fehlgeschlagenen 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 Absender-ID ungültig.
  • INTERNAL: Der Back-End-Server ist aus unbekannten Gründen fehlgeschlagen. Wiederholen Sie die Anfrage.
  • TOO_MANY_TOPICS: Zu viele Themen pro App-Instanz.
  • RESOURCE_EXHAUSTED: Zu viele Abo- oder Abo-Kündigungsanfragen in 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: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
{
   "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 Dienstes „Instanz-ID“ können Sie vorhandene iOS-APNs-Tokens im Bulk in Firebase Cloud Messaging importieren und sie gültigen Registrierungstokens zuordnen. Rufen Sie den Dienst „Instanz-ID“ an diesem Endpunkt auf und geben Sie eine Liste von APNs-Tokens im JSON-Text an:

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

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

Parameter

  • Authorization: Bearer <access_token>: Legen Sie diesen Parameter im Header fest. Fügen Sie ein kurzlebiges OAuth 2.0-Token als Wert des Headers Authorization hinzu. Weitere Informationen zum Abrufen dieses Tokens finden Sie unter Anmeldedaten manuell bereitstellen.
  • access_token_auth: true: Legen Sie diesen Parameter im Header fest.
  • application : Die Bundle-ID der App.
  • sandbox : Boolescher Wert, der die Sandbox-Umgebung (TRUE) oder die Produktionsumgebung (FALSE) angibt.
  • apns_tokens : Das Array von APNs-Tokens für die App-Instanzen, 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-Antworttext zurück. Für jedes in der Anfrage angegebene APNs-Token enthält die Ergebnisliste Folgendes:

  • Das APNs-Token.
  • Status. Entweder „OK“ oder eine Fehlermeldung, die den Fehler beschreibt.
  • Bei erfolgreichen Ergebnissen das Registrierungstoken, das FCM dem APNs-Token zuordnet.

Beispiel für eine POST-Anfrage

https://iid.googleapis.com/iid/v1:batchImport
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth:true
{
  "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"
        },
     ]
  }

Fehlerantworten

Aufrufe der Instance ID Server API geben die folgenden HTTP-Fehlercodes zurück:

  • HTTP status 400 (Bad request): Parameter der Anfrage 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) – Der Autorisierungsheader stimmt nicht mit authorizedEntity überein.
  • HTTP status 404 (Not found) - Ungültiger HTTP-Pfad oder IID-Token nicht gefunden. 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.