Serverreferenz

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

Informationen zu Anwendungsinstanzen abrufen

Wenn Sie Informationen zu einer App-Instanz abrufen möchten, rufen Sie den Instanz-ID-Dienst an diesem Endpunkt auf. Geben Sie dabei das Token der App-Instanz an:

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

Parameter

  • Authorization: Schlüssel=Ihr_API_SCHLÜSSEL. Legen Sie diesen Parameter in der Kopfzeile fest.
  • [optional] Boolescher Wert details: Legen Sie diesen Abfrageparameter auf true fest, um mit diesem Token verknüpfte FCM- oder GCM-Themeninformationen (falls vorhanden) abzurufen. 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 dem Token zugeordnet ist
  • authorizedEntity: Projekt-ID, die zum Senden an das Token autorisiert ist.
  • applicationVersion: Version der Anwendung.
  • appSignersha1-Fingerabdruck für die Signatur, die auf das Paket angewendet wurde. Gibt an, welche Partei die App signiert hat, z. B. Play Store.
  • 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. Beispiel: eine Liste von Themenabos.

Beispiel für eine GET-Anfrage

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Beispielergebnis

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "appSigner":"1a2bc3d4e5"
  "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 App-Instanzen erstellen

Mit der Instanz-ID-API können Sie Beziehungszuordnungen für App-Instanzen erstellen. Sie können beispielsweise einem Google Cloud Messaging-Thema ein Registrierungstoken zuordnen und die App-Instanz diesem Thema abonnieren. Die API bietet Methoden, um solche Beziehungen einzeln oder im Bulk zu erstellen.

Beziehungszuordnung für eine App-Instanz erstellen

Mit einem Registrierungstoken und einer unterstützten Beziehung können Sie eine Zuordnung erstellen. Sie können eine App-Instanz beispielsweise für ein Google Cloud Messaging-Thema abonnieren, indem Sie den Instanz-ID-Dienst an diesem Endpunkt aufrufen und das Token der App-Instanz wie hier gezeigt bereitstellen:

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

Parameter

  • Authorization: Schlüssel=Ihr_API_SCHLÜSSEL. Legen Sie diesen Parameter in der Kopfzeile 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:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Beispielergebnis

HTTP 200 OK
{}

Beziehungszuordnungen für mehrere App-Instanzen verwalten

Mit den Batchmethoden des Instanz-ID-Dienstes können Sie die Batchverwaltung von Anwendungsinstanzen ausführen. Beispielsweise haben Sie die Möglichkeit, einem FCM- oder GCM-Thema mehrere App-Instanzen gleichzeitig hinzuzufügen oder zu entfernen. Wenn Sie bis zu 1.000 App-Instanzen 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: Schlüssel=Ihr_API_SCHLÜSSEL. Legen Sie diesen Parameter in der Kopfzeile 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 zeigen 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_INDEX: Das angegebene Registrierungstoken ist für die Sender-ID ungültig.
  • INTERNAL: Der Back-End-Server ist aus unbekannten Gründen fehlgeschlagen. Wiederholen Sie die Anfrage.
  • TOO_MANY_TOPICS – Übermäßig viele Themen pro App-Instanz.
  • RESOURCE_EXHAUSTED: Zu viele Abo- oder Abo-Anfragen innerhalb eines kurzen Zeitraums. Versuchen Sie es mit exponentiellem Backoff.

Beispiel für eine POST-Anfrage

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
   "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 Google Cloud Messaging oder Firebase Cloud Messaging importieren und diesen gültigen Registrierungstokens zuordnen. Rufen Sie den Instanz-ID-Dienst an diesem Endpunkt auf und geben Sie eine Liste der APNs-Tokens im JSON-Textkörper an:

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

Der Antworttext enthält ein Array mit Instanz-ID-Registrierungstokens, die verwendet werden können, um FCM- oder GCM-Nachrichten an das entsprechende APNs-Gerätetoken zu senden.

Parameter

  • Authorization: Schlüssel=Ihr_API_SCHLÜSSEL. Legen Sie diesen Parameter in der Kopfzeile fest.
  • application : Bundle-ID der App.
  • sandbox : Boolescher Wert, der eine Sandbox-Umgebung (TRUE) oder eine Produktionsversion (FALSE) angibt
  • 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 APN-Token enthält die Ergebnisliste Folgendes:

  • Das APNs-Token.
  • Status. Entweder „OK“ oder eine Fehlermeldung, in der der Fehler beschrieben wird.
  • Für erfolgreiche Ergebnisse ist es das Registrierungstoken, das FCM oder GCM dem APNs-Token zugeordnet ist.

Beispiel für eine POST-Anfrage

https://iid.googleapis.com/iid/v1:batchImport
{
  "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"
        },
     ]
  }

Registrierungstokens für Push-Abos verwalten

Mit den Webmethoden des Instanz-ID-Dienstes können Sie vorhandene Push-Abos für Firebase Cloud Messaging importieren. Sie können sie auch aktualisieren und löschen.

Wenn Sie ein Push-Abo importieren, erhalten Sie ein Registrierungstoken. Mit diesem Token können Sie FCM-Funktionen wie Mitteilungen zu Themen und Gerätegruppen verwenden, um Benachrichtigungen auf Ihre Webanwendungen auszurichten.

Push-Abos importieren

Sie können Push-Abos mit dem Web-Endpunkt von InstanzID importieren:

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

Die Anfrage muss einen Autorisierungsheader, der auf ein OAuth 2.0-Zugriffstoken festgelegt ist, sowie einen Header für Kryptoschlüssel haben, der auf den Anwendungsserverschlüssel festgelegt ist, und das PushSubscription-Objekt im Anfragetext.

Der Antworttext enthält ein Registrierungstoken, das zum Senden von FCM- oder GCM-Nachrichten an die entsprechende Web-App-Instanz verwendet werden kann, ohne die Nutzlast zu verschlüsseln.

VAPID-Schlüsselpaar in die Konsole hochladen

Zum Importieren von Schlüsseln müssen Sie Zugriff auf Inhaberebene für das Firebase-Projekt haben. Importieren Sie Ihren vorhandenen öffentlichen und privaten Schlüssel in einem base64-URL-sicheren codierten Format:

  1. Öffnen Sie in der Firebase Console im Bereich Einstellungen den Tab Cloud Messaging und scrollen Sie zum Abschnitt Webkonfiguration.
  2. Suchen Sie auf dem Tab Web-Push-Zertifikate den Linktext „Vorhandenes Schlüsselpaar importieren“ und wählen Sie ihn aus.
  3. Geben Sie im Dialogfeld Schlüsselpaar importieren Ihren öffentlichen und den privaten Schlüssel in die entsprechenden Felder ein und klicken Sie auf Importieren. In der Console werden der öffentliche Schlüsselstring und das Datum angezeigt, an dem er hinzugefügt wurde.

OAuth2-Token abrufen: Anmeldedaten zur Erstellung von Zugriffstokens verwenden

Um ein Zugriffstoken für die Anfrage zu erstellen, müssen Sie ein Zugriffstoken erstellen und zur HTTP-Anfrage hinzufügen.

Node.js

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token

Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}

Fordern Sie den Bereich https://www.googleapis.com/auth/firebase.messaging an, um den Zugriff auf FCM zu autorisieren.

Parameter

  • Autorisierung: Bearer <access_token>. Legen Sie diesen Parameter in der Kopfzeile fest.
  • Kryptoschlüssel: p256ecdsa=APPLICATION_PUBLIC_KEY. Legen Sie diesen Parameter in der Kopfzeile fest.
  • Anfragetext: PushSubscription.toJson(). Übergib das Push-Abo an den HTTP-Text, ohne es zu parsen. Der Inhalt entspricht der W3C-Codierung von PushSubscription.

Antwort

Bei Erfolg gibt der Aufruf den HTTP-Status 200 OK und einen JSON-Ergebnistext zurück, der das IID-Token enthält.

Beispiel für eine POST-Anfrage

 https://iid.googleapis.com/v1/web/iid
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

Beispielergebnis

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Push-Abos aktualisieren

Sie können das mit Ihrem Registrierungstoken verknüpfte Push-Abo über den folgenden Endpunkt aktualisieren:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh

Parameter

  • Autorisierung: Bearer <access_token>. Legen Sie diesen Parameter in der Kopfzeile fest.
  • Kryptoschlüssel: p256ecdsa=APPLICATION_PUBLIC_KEY. Legen Sie diesen Parameter in der Kopfzeile fest.
  • Anfragetext: PushSubscription.toJson(). das Push-Abo an den HTTP-Text übergeben, ohne es zu parsen Der Inhalt entspricht der W3C-Codierung von PushSubscription.

Ergebnisse

Bei Erfolg gibt der Aufruf den HTTP-Status 200 und ein Registrierungstoken zurück. Dies kann das gleiche Token sein, das Sie in der Anfrage übergeben haben, oder ein neues Token.

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Beispiel für eine POST-Anfrage

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q"",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

Beispielergebnis

 HTTP 200 OK
 {
  "token":"KctODamlM4:CI2k_HHw...3P1"
 }

Push-Abos löschen

Mit einer DELETE-Anfrage werden die Push-Abodetails aus der FCM-Datenbank entfernt. Über das Push API-Protokoll können Sie weiterhin Nachrichten in Ihrer Webanwendung empfangen.

Zum Löschen eines Push-Abos senden Sie eine DELETE-Anfrage an:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN

Beispiel für eine DELETE-Anfrage

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

Beispielergebnis

 HTTP 200 OK {}

Fehlerantworten

Aufrufe an die Instanz-ID-Server-API geben die folgenden HTTP-Fehlercodes zurück:

  • HTTP status 400 (Bad request): Anfrageparameter fehlen oder sind ungültig. Ausführliche Informationen finden Sie in den Fehlermeldungen.
  • HTTP status 401 (Unauthorized) – Autorisierungsheader ist ungültig.
  • HTTP status 403 (Forbidden): Der Autorisierungsheader entspricht nicht dem authorizedEntity.
  • HTTP status 404 (Not found): Ungültiger HTTP-Pfad oder ungültiges IID-Token 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.