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 Instance ID-Dienst an diesem Endpunkt auf und geben Sie das Token der App-Instanz 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 OAuth2-Token als Wert des Headers Authorization 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] boolean 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, lautet die Standardeinstellung false.

Ergebnisse

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

  • application: Der mit dem Token verknüpfte Paketname.
  • authorizedEntity: Die Projekt-ID des Projekts, das berechtigt ist, das Token zu senden.
  • 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 festgelegt ist:

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

Beispielanfrage für GET

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 Beziehungsdiagramme für App-Instanzen erstellen. Sie können beispielsweise ein Registrierungstoken einem FCM-Thema zuordnen und so 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

Mit einem Registrierungstoken und einer unterstützten Beziehung können Sie eine Zuordnung erstellen. Sie können beispielsweise eine App-Instanz für ein FCM-Thema registrieren, indem Sie den Instance ID-Dienst 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 OAuth2-Token als Wert des Headers Authorization 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.

Beispielanfrage für POST

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 Instance ID-Dienstes können Sie App-Instanzen im Batch verwalten. Sie können beispielsweise App-Instanzen in großen Mengen 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 Instance ID-Dienst 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 OAuth2-Token als Wert des Headers Authorization 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 Themenname.
  • 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 deuten auf ein erfolgreiches Abonnieren des Tokens 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 Registrierungs-Token ist für die Sender-ID ungültig.
  • INTERNAL: Der Backend-Server ist aus unbekannten Gründen fehlgeschlagen. Wiederholen Sie die Anfrage.
  • TOO_MANY_TOPICS: Zu viele Themen pro App-Instanz.
  • RESOURCE_EXHAUSTED: Innerhalb eines kurzen Zeitraums wurden zu viele Anfragen zum Abonnieren oder Abbestellen gesendet. Wiederholen Sie den Vorgang mit exponentiellem Backoff.

Beispielanfrage für POST

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 Instance ID-Dienstes können Sie vorhandene iOS-APNs-Tokens in Firebase Cloud Messaging importieren und gültigen Registrierungstokens zuordnen. Rufen Sie den Instance ID-Dienst an diesem Endpunkt auf und geben Sie eine Liste von APNs-Tokens im JSON-Body an:

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

Der Antworttext enthält ein Array von Instance ID-Registrierungstokens, 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 OAuth2-Token als Wert des Headers Authorization 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 die Produktion (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-Ergebnistext zurück. Für jedes in der Anfrage angegebene APNs-Token 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 FCM dem APNs-Token zuordnet.

Beispielanfrage für POST

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

Bei Aufrufen der Instance ID Server API werden die folgenden HTTP-Fehlercodes zurückgegeben:

  • HTTP status 400 (Bad request) – Anfrageparameter fehlen oder sind ungültig. Detaillierte 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. Detaillierte Informationen finden Sie in den Fehlermeldungen.
  • HTTP status 503 (Service unavailable) – Dienst nicht verfügbar. Wiederholen Sie die Anfrage mit exponentiellem Backoff.