Serverreferenz

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

Informationen zu Anwendungsinstanzen abrufen

Um Informationen zu einer Anwendungsinstanz zu erhalten, rufen Sie den Instanz-ID-Dienst an diesem Endpunkt auf und geben Sie das Token der Anwendungsinstanz 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 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 ggf. Informationen zu Abos für das FCM-Thema 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: der mit dem Token verknüpfte Paketname.
  • 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 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 Anwendungsinstanzen erstellen

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

Beziehungszuordnung für eine Anwendungsinstanz erstellen

Mit einem Registrierungstoken und einer unterstützten Beziehung können Sie eine Zuordnung erstellen. Sie können z. B. für eine Anwendungsinstanz ein FCM-Thema abonnieren, indem Sie den Instanz-ID-Dienst an diesem Endpunkt aufrufen und das Token der Anwendungsinstanz wie folgt 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 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
{}

Beziehungszuordnungen für mehrere Anwendungsinstanzen verwalten

Mit den Batchmethoden des Instanz-ID-Dienstes können Sie Anwendungsinstanzen im Batch verwalten. Sie können beispielsweise Anwendungsinstanzen im Bulk zu einem FCM-Thema hinzufügen oder daraus entfernen. Wenn Sie bis zu 1.000 Anwendungsinstanzen pro API-Aufruf aktualisieren möchten, rufen Sie den Instanz-ID-Dienst an diesem Endpunkt auf und geben Sie die App-Instanztokens 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 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 Anwendungsinstanzen, die Sie hinzufügen oder entfernen möchten.

Ergebnisse

Bei Erfolg gibt der Aufruf den HTTP-Status 200 zurück. Leere Ergebnisse zeigen ein erfolgreiches Abo für das Token an. 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 Sender-ID nicht gü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 Abo- oder 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 Instanz-ID-Dienstes können Sie vorhandene iOS-APNs-Tokens im Bulk in Firebase Cloud Messaging importieren und gültigen Registrierungstokens zuordnen. Rufen Sie den Instanz-ID-Dienst an diesem Endpunkt auf und geben Sie eine Liste der APNs-Tokens im JSON-Text an:

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

Der Antworttext enthält ein Array mit Instanz-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 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 zur Angabe der Sandbox-Umgebung (TRUE) oder Produktion (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 APNs-Token enthält die Ergebnisliste Folgendes:

  • Das APNs-Token.
  • Status. Entweder OK oder eine Fehlermeldung, die den Fehler beschreibt.
  • Für erfolgreiche Ergebnisse das Registrierungstoken, das FCM dem APNs-Token zugeordnet ist.

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 an die Instanz-ID-Server-API geben die folgenden HTTP-Fehlercodes zurück:

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