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 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 dem Authorization-Header ein kurzlebiges OAuth2-Token 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-Themenabos (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 mit dem Token verknüpft ist.
  • authorizedEntity – Projekt-ID, die zum Senden an das Token autorisiert ist.
  • applicationVersion ist die 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 mit dem Token verknüpft sind. z. B. 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"}
    }
  }
}

Beziehungszuordnungen für Anwendungsinstanzen erstellen

Mit der Instance ID API können Sie Beziehungszuordnungen für Anwendungsinstanzen erstellen. Sie können beispielsweise ein Registrierungstoken einem FCM-Thema zuordnen und 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 beispielsweise für eine Anwendungsinstanz ein FCM-Thema abonnieren. Dazu rufen Sie den Instanz-ID-Dienst an diesem Endpunkt auf und geben das Token der Anwendungsinstanz so an:

 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 dem Authorization-Header ein kurzlebiges OAuth2-Token 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 Anwendungsinstanzen im Batch verwalten. Sie können beispielsweise App-Instanzen im Bulk zu einem FCM-Thema hinzufügen oder 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 Anwendungsinstanztokens 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 dem Authorization-Header ein kurzlebiges OAuth2-Token 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 weisen auf ein erfolgreiches Abo 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 Registrierungstoken ist für die Absender-ID nicht gültig.
  • INTERN: Der Backend-Server ist aus unbekannten Gründen fehlgeschlagen. Wiederholen Sie die Anfrage.
  • TOO_MANY_TOPICS: Übermäßig viele Themen pro Anwendungsinstanz.
  • RESOURCE_EXHAUSTED: Zu viele Abonnement- oder Kündigungsanfragen innerhalb eines kurzen Zeitraums. 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 sie gültigen Registrierungstokens zuordnen. Rufen Sie den Instanz-ID-Dienst an diesem Endpunkt auf und geben Sie im JSON-Text eine Liste der APNs-Tokens 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 dem Authorization-Header ein kurzlebiges OAuth2-Token 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, um die Sandbox-Umgebung (TRUE) oder Produktion (FALSE) anzugeben
  • 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 bereitgestellte 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 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): 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 dem 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): Der Dienst ist nicht verfügbar. Wiederholen Sie die Anfrage mit exponentiellem Backoff.