Documentation de référence sur le serveur

L'implémentation du serveur est facultative. Utilisez le service Instance ID 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 Instance ID à ce point de terminaison en fournissant le jeton de l'instance d'application, comme indiqué ci-dessous :

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

Paramètres

  • Authorization: Bearer <access_token>. Définissez ce paramètre dans l'en-tête. Ajoutez un jeton OAuth2 à courte durée de vie comme valeur de l'en-tête Authorization. Pour en savoir plus sur l'obtention de ce jeton, consultez Fournir manuellement des identifiants.
  • access_token_auth: true. 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 (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

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

  • application : nom du package associé au jeton.
  • authorizedEntity : projectId autorisé à envoyer au jeton.
  • applicationVersion : version de l'application.
  • platform : renvoie ANDROID, IOS ou CHROME pour indiquer la plate-forme de l'appareil à laquelle appartient le jeton.

Si l'indicateur details est défini :

  • rel : relations associées au jeton. Par exemple, une liste d'abonnements à des sujets.

Exemple de requête GET

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

Exemple de résultat

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

Créer des cartes de relations pour les instances d'application

L'API Instance ID vous permet de créer des cartes de relations pour les instances d'application. Par exemple, vous pouvez mapper un jeton d'enregistrement à un sujet FCM, en abonnant l'instance d'application au sujet. L'API fournit des méthodes pour créer ces relations individuellement et en bloc.

Créer un mappage de relation pour une instance d'application

Étant donné 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 FCM en appelant le service Instance ID à ce point de terminaison et en fournissant le jeton de l'instance d'application, comme indiqué ci-dessous :

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

Paramètres

  • Authorization: Bearer <access_token>. Définissez ce paramètre dans l'en-tête. Ajoutez un jeton OAuth2 à courte durée de vie comme valeur de l'en-tête Authorization. Pour en savoir plus sur l'obtention de ce jeton, consultez Fournir manuellement des identifiants.
  • access_token_auth: true. 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: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

Exemple de résultat

HTTP 200 OK
{}

Gérer les cartes de relations pour plusieurs instances d'application

À l'aide des méthodes par lot du service Instance ID, vous pouvez effectuer une gestion par lot des instances d'application. Par exemple, vous pouvez ajouter ou supprimer en bloc des instances d'application à un sujet FCM. Pour mettre à jour jusqu'à 1 000 instances d'application par appel d'API, appelez le service Instance ID à 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: Bearer <access_token>. Définissez ce paramètre dans l'en-tête. Ajoutez un jeton OAuth2 à courte durée de vie comme valeur de l'en-tête Authorization. Pour en savoir plus sur l'obtention de ce jeton, consultez Fournir manuellement des identifiants.
  • access_token_auth: true. Définissez ce paramètre dans l'en-tête.
  • to : nom du sujet.
  • registration_tokens : tableau de jetons IID pour les instances d'application que vous souhaitez ajouter ou supprimer.

Résultats

En cas de réussite, l'appel renvoie l'état HTTP 200. Des résultats vides indiquent que l'abonnement au jeton a réussi. En cas d'échec de l'abonnement, 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 de l'expéditeur.
  • INTERNAL : le serveur backend a échoué 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 requêtes d'abonnement ou de désabonnement 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: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
{
   "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

À l'aide de la méthode batchImport du service Instance ID, vous pouvez importer en bloc des jetons APNs iOS existants dans Firebase Cloud Messaging et les mapper à des jetons d'enregistrement valides. Appelez le service Instance ID à 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 Instance ID prêts à être utilisés pour envoyer des messages FCM au jeton d'appareil APNs correspondant.

Paramètres

  • Authorization: Bearer <access_token>. Définissez ce paramètre dans l'en-tête. Ajoutez un jeton OAuth2 à courte durée de vie comme valeur de l'en-tête Authorization. Pour en savoir plus sur l'obtention de ce jeton, consultez Fournir manuellement des identifiants.
  • access_token_auth: true. Définissez ce paramètre dans l'en-tête.
  • application : ID de bundle de l'application.
  • sandbox : valeur booléenne indiquant l'environnement de bac à sable (TRUE) ou la production (FALSE)
  • apns_tokens : tableau de jetons APNs pour les instances d'application 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 APNs fourni dans la requête, la liste des résultats inclut les éléments suivants :

  • Le jeton APNs.
  • État. OK ou un message d'erreur décrivant l'échec.
  • Pour les résultats positifs, le jeton d'enregistrement que FCM mappe au jeton APNs.

Exemple de requête POST

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

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

Réponses d'erreur

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

  • HTTP status 400 (Bad request) : paramètres de requête manquants ou non valides. Consultez les messages d'erreur pour obtenir des informations détaillées.
  • HTTP status 401 (Unauthorized) : en-tête d'autorisation non 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. Consultez les messages d'erreur pour obtenir des informations détaillées.
  • HTTP status 503 (Service unavailable) : service indisponible. Réessayez d'envoyer la requête avec un intervalle exponentiel entre les tentatives.