Documentation de référence sur le serveur

L'implémentation du serveur est facultative. Utilisez le service d'ID d'instance si vous souhaitez effectuer ces opérations:

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: key=YOUR_API_KEY. 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. Si aucune valeur n'est spécifiée, la valeur par défaut est false.

Résultats

Si l'appel aboutit, l'appel renvoie l'état HTTP 200 et un objet JSON contenant les éléments suivants:

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

Si l'indicateur details est défini:

  • 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 de relations pour les instances d'application

L'API Instance ID vous permet de créer des mappages de relations 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 de telles relations individuellement et de façon groupée.

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

Vous pouvez créer un mappage en fonction d'un jeton d'enregistrement et d'une relation compatible. 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: key=YOUR_API_KEY. Définissez ce paramètre dans l'en-tête.

Résultats

Si l'appel aboutit, 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 de relation pour plusieurs instances d'application

Les méthodes de traitement par lot du service d'ID d'instance vous permettent d'effectuer une gestion par lot 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: key=YOUR_API_KEY. 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

Si l'appel aboutit, l'appel renvoie l'état HTTP 200. Les résultats vides indiquent que l'abonnement au jeton a abouti. 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'ID d'expéditeur.
  • INTERNE : échec du serveur backend pour des raisons inconnues. Réessayez d'envoyer la requête.
  • TOO_MANY_TOPICS : nombre excessif de thèmes par instance d'application.
  • RESOURCE_EXHAUSTED : requêtes d'abonnement ou de désabonnement trop nombreuses sur une courte période. Réessayez 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

Avec la méthode batchImport du service d'ID d'instance, vous pouvez importer de manière groupée des jetons APN iOS existants vers 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: key=YOUR_API_KEY. Définissez ce paramètre dans l'en-tête.
  • application : ID de bundle de l'application.
  • sandbox : booléen pour indiquer l'environnement de bac à sable (TRUE) ou la production (FALSE)
  • apns_tokens : tableau des jetons APNs des instances d'appli que vous souhaitez ajouter ou supprimer. 100 jetons maximum par requête.

Résultats

Si l'appel aboutit, l'appel renvoie l'état HTTP 200 et un corps de résultat JSON. Pour chaque jeton APNs fourni dans la requête, la liste des résultats comprend les informations suivantes:

  • Jeton APNs.
  • État. OK ou message d'erreur décrivant l'échec.
  • Pour obtenir des résultats réussis, le jeton d'enregistrement que FCM ou GCM mappe avec le 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'inscription 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 les fonctionnalités FCM comme 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 de l'ID d'instance:

 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 cryptomonnaie 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 de l'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 de niveau propriétaire au projet Firebase. Importez votre clé publique et privée existante sous une forme encodée en URL sécurisée en base64:

  1. Ouvrez l'onglet Cloud Messaging du volet Paramètres de la console Firebase, puis faites défiler la page jusqu'à la section Configuration Web.
  2. Dans l'onglet Certificats Web Push, recherchez et sélectionnez le texte du lien "Importer une paire de clés existante".
  3. Dans la boîte de dialogue Importer une paire de clés, indiquez 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: obtenir des jetons d'accès à l'aide d'identifiants

Afin de créer un jeton d'accès pour la requête, vous devez frapper 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(). Transmettre l'abonnement push au corps HTTP sans l'analyser. Le contenu correspond à l'encodage W3C de PushSubscription.

Réponse

Si l'appel aboutit, l'appel renvoie l'état HTTP 200 "OK", ainsi qu'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(). Transmettre l'abonnement push au corps HTTP sans l'analyser. Le contenu correspond à l'encodage W3C de PushSubscription.

Résultats

Si l'appel aboutit, 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 d'erreur

Les appels d'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) : le chemin HTTP ou le jeton IID non valide sont introuvables. 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.