Serverreferenz

Die Serverimplementierung ist optional. Verwenden Sie den Instance ID-Dienst, 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 Instanz-ID-Dienst unter diesem Endpunkt auf und geben Sie das Token der App-Instanz an, wie hier gezeigt:

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

Parameter

  • Authorization: Bearer <access_token>: Legen Sie diesen Parameter im Header fest. Füge ein kurzlebiges OAuth2-Token als Wert für den Authorization-Header hinzu. Weitere Informationen zum Abrufen dieses Tokens finden Sie unter Anmeldedaten manuell angeben.
  • access_token_auth: true: Legen Sie diesen Parameter im Header fest.
  • [optional] boolescher Wert details: Legen Sie diesen Abfrageparameter auf true fest, um Informationen zu FCM-Themenabonnements (falls vorhanden) abzurufen, die mit diesem Token verknüpft sind. Wenn nicht angegeben, lautet der Standardwert false.

Ergebnisse

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

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

Wenn das Flag details gesetzt ist:

  • rel: Beziehungen, die mit dem Token verknüpft sind. Beispiel: Eine Liste mit 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-Verfahren.

Beziehungszuordnung für eine App-Instanz erstellen

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

 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üge ein kurzlebiges OAuth2-Token als Wert für den Authorization-Header hinzu. Weitere Informationen zum Abrufen dieses Tokens finden Sie unter Anmeldedaten manuell angeben.
  • 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 Batchmethoden des Instanz-ID-Dienstes können Sie App-Instanzen im Batch verwalten. Sie können beispielsweise App-Instanzen einem FCM-Thema im Bulk hinzufügen oder daraus entfernen. Wenn Sie bis zu 1.000 App-Instanzen pro API-Aufruf aktualisieren möchten, rufen Sie den Dienst „Instance ID“ unter diesem Endpunkt auf und geben Sie die Tokens der App-Instanzen 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üge ein kurzlebiges OAuth2-Token als Wert für den Authorization-Header hinzu. Weitere Informationen zum Abrufen dieses Tokens finden Sie unter Anmeldedaten manuell angeben.
  • access_token_auth: true: Legen Sie diesen Parameter im Header fest.
  • to : Der Name des Themas.
  • registration_tokens : Das Array der 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 geben an, dass das Token erfolgreich abonniert wurde. 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.
  • INTERN: Der Backend-Server ist aus unbekannten Gründen fehlgeschlagen. Wiederholen Sie die Anfrage.
  • TOO_MANY_TOPICS – Zu viele Themen pro App-Instanz.
  • RESOURCE_EXHAUSTED: Zu viele Anfragen zum Abonnieren oder Abbestellen 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: 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 APN-Tokens erstellen

Mit der batchImport-Methode des Instance ID-Dienstes können Sie vorhandene iOS-APNs-Tokens im Bulk-Verfahren in Firebase Cloud Messaging importieren und ihnen gültige Registrierungstokens zuordnen. Rufen Sie den Instance ID-Dienst unter diesem Endpunkt auf und geben Sie im JSON-Textkörper eine Liste von APNs-Tokens 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üge ein kurzlebiges OAuth2-Token als Wert für den Authorization-Header hinzu. Weitere Informationen zum Abrufen dieses Tokens finden Sie unter Anmeldedaten manuell angeben.
  • access_token_auth: true: Legen Sie diesen Parameter im Header fest.
  • application : Bundle-ID der App.
  • sandbox : Boolescher Wert, der angibt, ob es sich um eine Sandbox-Umgebung (TRUE) oder eine Produktionsumgebung (FALSE) handelt
  • apns_tokens : Das Array der 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-Ergebnisbereich zurück. Für jedes APNs-Token, das in der Anfrage angegeben wurde, enthält die Ergebnisliste Folgendes:

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

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) – Anfrageparameter fehlen oder sind ungültig. Weitere Informationen finden Sie in den Fehlermeldungen.
  • HTTP status 401 (Unauthorized) – Autorisierungsheader ungültig
  • HTTP status 403 (Forbidden) – 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) – Dienst nicht verfügbar. Wiederholen Sie die Anfrage mit exponentiellem Backoff.