Documentation de référence sur le serveur

La mise en œuvre du serveur est facultative. Utilisez le service d'ID d'instance si vous souhaitez effectuer les opérations suivantes:

Obtenir des informations sur les instances d'application

Pour obtenir des informations sur une instance d'application, appelez le service d'ID d'instance à ce point de terminaison, en fournissant le jeton de l'instance d'application comme indiqué:

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

Paramètres

  • Authorization: clé=VOTRE_CLÉ_API. Définissez ce paramètre dans l'en-tête.
  • [Facultatif] Booléen details: définissez ce paramètre de requête sur true pour obtenir les informations d'abonnement au sujet FCM ou GCM (le cas échéant) associées à ce jeton. Lorsqu'il n'est pas spécifié, la valeur par défaut est false.

Résultats

En cas de réussite, l'appel renvoie l'état HTTP 200 et un objet JSON contenant:

  • application : nom du package associé au jeton.
  • authorizedEntity : ID du projet autorisé à envoyer au jeton.
  • applicationVersion : version de l'application.
  • appSigner : empreinte sha1 pour la signature appliquée au package. Indique qui a signé l'application,par exemple Play Store.
  • platform : renvoie ANDROID, IOS ou CHROME pour indiquer la plate-forme de l'appareil à laquelle le jeton appartient.

Si l'option details est définie:

  • rel : relations associées au jeton. (liste d'abonnements à des sujets, par exemple).

Exemple de requête GET

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

Exemple de résultat

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"}
    }
  }
}

Créer des mappages relationnels pour les instances d'application

L'API Instance ID vous permet de créer des mappages relationnels pour les instances d'application. Par exemple, vous pouvez mapper un jeton d'enregistrement à un sujet Google Cloud Messaging et abonner l'instance d'application à ce sujet. L'API fournit des méthodes permettant de créer ces relations individuellement et de façon groupée.

Créer un mappage relationnel pour une instance d'application

Avec un jeton d'enregistrement et une relation compatible, vous pouvez créer un mappage. Par exemple, vous pouvez abonner une instance d'application à un sujet Google Cloud Messaging en appelant le service d'ID d'instance à ce point de terminaison, en fournissant le jeton de l'instance d'application comme indiqué:

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

Paramètres

  • Authorization: clé=VOTRE_CLÉ_API. Définissez ce paramètre dans l'en-tête.

Résultats

En cas de réussite, l'appel renvoie l'état HTTP 200.

Exemple de requête POST

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

Exemple de résultat

HTTP 200 OK
{}

Gérer les mappages relationnels pour plusieurs instances d'application

Les méthodes de traitement par lot du service d'ID d'instance vous permettent de gérer par lots des instances d'application. Par exemple, vous pouvez ajouter ou supprimer des instances d'application de manière groupée dans un sujet FCM ou GCM. Pour mettre à jour jusqu'à 1 000 instances d'application par appel d'API, appelez le service d'ID d'instance à ce point de terminaison en fournissant les jetons d'instance d'application dans le corps JSON:

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

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

Paramètres

  • Authorization: clé=VOTRE_CLÉ_API. Définissez ce paramètre dans l'en-tête.
  • to : nom du sujet.
  • registration_tokens : tableau des jetons IID des instances d'application que vous souhaitez ajouter ou supprimer.

Résultats

En cas de réussite, l'appel renvoie l'état HTTP 200. Les résultats vides indiquent que l'abonnement au jeton a réussi. Pour les abonnements ayant échoué, le résultat contient l'un des codes d'erreur suivants:

  • NOT_FOUND : le jeton d'enregistrement a été supprimé ou l'application a été désinstallée.
  • INVALID_ARGUMENT : le jeton d'enregistrement fourni n'est pas valide pour l'identifiant de l'expéditeur.
  • INTERNE : échec du serveur backend pour des raisons inconnues. Réessayez d'envoyer la requête.
  • TOO_MANY_TOPICS : nombre excessif de sujets par instance d'application
  • RESOURCE_EXHAUSTED : trop de demandes d'abonnement ou de désabonnement sur une courte période Réessayer avec un intervalle exponentiel entre les tentatives.

Exemple de requête POST

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..."],
}

Exemple de résultat

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

Créer des jetons d'enregistrement pour les jetons APNs

La méthode batchImport du service d'ID d'instance vous permet d'importer de manière groupée des jetons APN iOS existants dans Google Cloud Messaging ou Firebase Cloud Messaging, en les mappant à des jetons d'enregistrement valides. Appelez le service d'ID d'instance à ce point de terminaison en fournissant une liste de jetons APNs dans le corps JSON:

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

Le corps de la réponse contient un tableau de jetons d'enregistrement d'ID d'instance prêts à être utilisés pour envoyer des messages FCM ou GCM au jeton d'appareil APN correspondant.

Paramètres

  • Authorization: clé=VOTRE_CLÉ_API. Définissez ce paramètre dans l'en-tête.
  • application : identifiant de groupe de l'application.
  • sandbox : booléen pour indiquer l'environnement de bac à sable (TRUE) ou la production (FALSE).
  • apns_tokens : tableau des jetons APN pour les instances d'applications que vous souhaitez ajouter ou supprimer. 100 jetons maximum par requête.

Résultats

En cas de réussite, l'appel renvoie l'état HTTP 200 et un corps de résultat JSON. Pour chaque jeton APN fourni dans la requête, la liste des résultats inclut:

  • Jeton APNs.
  • État. OK ou message d'erreur décrivant l'échec.
  • Pour que les résultats aboutissent, le jeton d'enregistrement que FCM ou GCM est associé au jeton APNs.

Exemple de requête POST

https://iid.googleapis.com/iid/v1:batchImport
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
  }
}

Exemple de résultat

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

Gérer les jetons d'enregistrement pour les abonnements push

Les méthodes Web du service d'ID d'instance vous permettent d'importer des abonnements push existants pour Firebase Cloud Messaging. Vous pouvez également les mettre à jour et les supprimer.

Lorsque vous importez un abonnement push, vous recevez un jeton d'enregistrement. Ce jeton vous permet d'utiliser des fonctionnalités FCM telles que la messagerie thématique et la messagerie de groupe d'appareils pour cibler les notifications sur vos applications Web.

Importer des abonnements push

Vous pouvez importer des abonnements push à l'aide du point de terminaison Web d'InstanceID:

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

La requête doit contenir un en-tête d'autorisation défini sur un jeton d'accès OAuth 2.0, un en-tête de clé cryptographique défini sur votre clé de serveur d'application et l'objet PushSubscription dans le corps de la requête.

Le corps de la réponse contient un jeton d'enregistrement prêt à être utilisé pour envoyer des messages FCM ou GCM à l'instance d'application Web correspondante sans avoir à chiffrer la charge utile.

Importer votre paire de clés VAPID dans la console

Pour importer des clés, vous devez disposer d'un accès propriétaire au projet Firebase. Importez votre clé publique et privée existante au format sécurisé en base64 d'URL:

  1. Ouvrez l'onglet Cloud Messaging du volet Paramètres de la console Firebase et faites défiler la page jusqu'à la section Configuration Web.
  2. Dans l'onglet Certificats Web Push, recherchez le texte du lien "Importer une paire de clés existante".
  3. Dans la boîte de dialogue Importer une paire de clés, saisissez vos clés publique et privée dans les champs correspondants, puis cliquez sur Importer. La console affiche la chaîne de clé publique et la date d'ajout.

Récupérer un jeton OAuth2: utiliser les identifiants pour générer les jetons d'accès

Afin de créer un jeton d'accès pour la requête, vous devez générer le jeton d'accès et l'ajouter à la requête HTTP.

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);
      });
}
index.js

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
configure.py

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();
}
Configure.java

Pour autoriser l'accès à FCM, demandez le champ d'application https://www.googleapis.com/auth/firebase.messaging.

Paramètres

  • Autorisation: Bearer <access_token> Définissez ce paramètre dans l'en-tête.
  • Clé de chiffrement : p256ecdsa=APPLICATION_PUBLIC_KEY. Définissez ce paramètre dans l'en-tête.
  • Corps de la requête: PushSubscription.toJson(). Transmettez l'abonnement push au corps HTTP sans l'analyser. Le contenu correspond à l'encodage W3C de PushSubscription.

Réponse

En cas de réussite, l'appel renvoie l'état HTTP 200 OK et un corps de résultat JSON contenant le jeton IID.

Exemple de requête POST

 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"
    }
 }

Exemple de résultat

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

Mettre à jour les abonnements push

Vous pouvez mettre à jour l'abonnement push associé à votre jeton d'enregistrement à l'aide du point de terminaison suivant:

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

Paramètres

  • Autorisation : Bearer <access_token> Définissez ce paramètre dans l'en-tête.
  • Clé de chiffrement: p256ecdsa=APPLICATION_PUBLIC_KEY. Définissez ce paramètre dans l'en-tête.
  • Corps de la requête : PushSubscription.toJson(). Transmettez l'abonnement push au corps HTTP sans l'analyser. Le contenu correspond à l'encodage W3C de PushSubscription.

Résultats

En cas de réussite, l'appel renvoie l'état HTTP 200 et un jeton d'enregistrement. Il peut s'agir du même jeton que vous avez transmis dans la requête ou d'un nouveau jeton.

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

Exemple de requête POST

 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"
    }
 }

Exemple de résultat

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

Supprimer des abonnements push

Une requête DELETE supprime les détails de l'abonnement push de la base de données FCM. Vous pouvez toujours recevoir des messages dans votre application Web à l'aide du protocole d'API Push.

Pour supprimer un abonnement push, envoyez une requête DELETE à:

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

Exemple de requête DELETE

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

Exemple de résultat

 HTTP 200 OK {}

Réponses aux erreurs

Les appels vers l'API du serveur d'ID d'instance renvoient les codes d'erreur HTTP suivants:

  • HTTP status 400 (Bad request) : les paramètres de requête sont manquants ou incorrects. Pour en savoir plus, consultez les messages d'erreur.
  • HTTP status 401 (Unauthorized) : l'en-tête d'autorisation n'est pas valide.
  • HTTP status 403 (Forbidden) : l'en-tête d'autorisation ne correspond pas à authorizedEntity.
  • HTTP status 404 (Not found) - Chemin HTTP non valide ou jeton IID introuvable. Pour en savoir plus, consultez les messages d'erreur.
  • HTTP status 503 (Service unavailable) : service indisponible. Réessayez d'exécuter la requête avec un intervalle exponentiel entre les tentatives.