Envoyer un message à l'aide de l'API FCM HTTP v1

L'API HTTP v1 FCM vous permet de créer des requêtes de message et de les envoyer aux types de cibles suivants :

  • Nom du sujet
  • Condition
  • Jeton d'enregistrement de l'appareil
  • Nom du groupe d'appareils (obsolète, sera supprimé le 29 septembre 2027)

Vous pouvez envoyer des messages avec une charge utile de notification composée de champs prédéfinis, une charge utile de données de vos propres champs définis par l'utilisateur ou un message contenant les deux types de charge utile. Pour en savoir plus, consultez Types de messages.

Autoriser les requêtes d'envoi HTTP v1

En fonction des détails de votre environnement de serveur, utilisez une combinaison de ces stratégies pour autoriser les requêtes du serveur vers les services Firebase :

  • Identifiants par défaut de l'application Google (ADC)
  • Un fichier JSON de compte de service
  • Jeton d'accès OAuth 2.0 de courte durée dérivé d'un compte de service

Si votre application s'exécute sur Compute Engine, Google Kubernetes Engine, App Engine ou Cloud Functions (y compris Cloud Functions for Firebase), utilisez les identifiants par défaut de l'application (ADC). L'ADC utilise votre compte de service par défaut existant pour obtenir des identifiants permettant d'autoriser les requêtes. Il permet également de tester de manière flexible l'environnement local via la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS. Pour automatiser au maximum le flux d'autorisation, utilisez les ADC avec les bibliothèques de serveur du SDK Admin.

Si votre application s'exécute sur un environnement de serveur non Google, vous devez télécharger un fichier JSON de compte de service à partir de votre projet Firebase. Tant que vous avez accès à un système de fichiers contenant le fichier de clé privée, vous pouvez utiliser la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS pour autoriser les requêtes avec ces identifiants obtenus manuellement. Si vous n'avez pas accès à ce fichier, vous devez référencer le fichier de compte de service dans votre code, ce qui doit être fait avec une extrême prudence en raison du risque d'exposition de vos identifiants.

Fournir des identifiants à l'aide d'ADC

Les identifiants par défaut de l'application Google (ADC) vérifient vos identifiants dans l'ordre suivant :

  1. ADC vérifie si la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS est définie. Si la variable est définie, ADC utilise le fichier de compte de service auquel renvoie cette variable.

  2. Si la variable d'environnement n'est pas définie, ADC utilise le compte de service par défaut que fournissent Compute Engine, Google Kubernetes Engine, App Engine et Cloud Functions pour les applications exécutées sur ces services.

  3. Si les ADC ne peuvent pas utiliser l'un des identifiants ci-dessus, le système génère une erreur.

L'exemple de code du SDK Admin suivant illustre cette stratégie. Il n'indique pas explicitement les identifiants de l'application. Cependant, l'ADC peut trouver implicitement les identifiants tant que la variable d'environnement est définie, ou tant que l'application s'exécute sur Compute Engine, Google Kubernetes Engine, App Engine ou Cloud Functions.

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

Fournir des identifiants manuellement

Les projets Firebase sont compatibles avec les comptes de service Google, que vous pouvez utiliser pour appeler les API du serveur Firebase depuis votre serveur d'applications ou votre environnement de confiance. Si vous développez du code localement ou déployez votre application sur site, vous pouvez utiliser les identifiants obtenus à l'aide de ce compte de service pour autoriser les requêtes du serveur.

Vous pouvez afficher tous les comptes de service de votre projet Firebase dans l'onglet Paramètres > Comptes de service.

Pour authentifier un compte de service et l'autoriser à accéder aux services Firebase, vous devez générer un fichier de clé privée au format JSON.

Pour générer un fichier de clé privée pour votre compte de service :

  1. Dans la console Firebase, accédez à l'onglet Paramètres > Comptes de service.

  2. Cliquez sur Générer une clé privée, puis confirmez en cliquant sur Générer une clé.

  3. Stockez de manière sécurisée le fichier JSON contenant la clé.

Lorsque vous autorisez l'accès via un compte de service, vous avez deux possibilités pour fournir les identifiants à votre application. Vous pouvez définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS ou transmettre explicitement le chemin d'accès à la clé de compte de service dans le code. La première option est plus sécurisée et vivement recommandée.

Pour définir la variable d'environnement :

Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur le chemin d'accès du fichier JSON contenant la clé de votre compte de service. Cette variable ne s'applique qu'à la session d'interface système actuelle. Par conséquent, si vous ouvrez une nouvelle session, vous devez la définir à nouveau.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

Avec PowerShell :

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Une fois les étapes ci-dessus terminées, le service d'identifiants par défaut de l'application (ADC) peut déterminer implicitement vos identifiants, ce qui vous permet d'utiliser les identifiants du compte de service lors des tests ou de l'exécution dans des environnements non Google.

Utiliser des identifiants pour générer des jetons d'accès

Sauf si vous utilisez Firebase Admin SDK, qui gère l'autorisation automatiquement, vous devez créer le jeton d'accès et l'ajouter pour envoyer des requêtes.

Utilisez vos identifiants Firebase avec la bibliothèque Google Auth pour le langage de votre choix afin de récupérer un jeton d'accès OAuth 2.0 de courte durée :

Node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    const key = require('../placeholders/service-account.json');
    const jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

Dans cet exemple, la bibliothèque cliente des API Google authentifie la requête avec un jeton Web JSON (JWT). Pour en savoir plus, consultez Jetons Web JSON.

Python

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

  :return: Access token.
  """
  credentials = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
  request = google.auth.transport.requests.Request()
  credentials.refresh(request)
  return credentials.token

Java

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

Une fois votre jeton d'accès arrivé à expiration, la méthode d'actualisation du jeton est appelée automatiquement pour récupérer un jeton d'accès mis à jour.

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

Pour ajouter le jeton d'accès à un en-tête de requête HTTP :

Ajoutez le jeton en tant que valeur de l'en-tête Authorization au format Authorization: Bearer <access_token> :

Node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

Python

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}

Java

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;

Autoriser un compte de service d'un autre projet

Vous pouvez envoyer des messages pour un projet, le "projet cible", tout en utilisant un jeton OAuth 2.0 généré à partir d'un compte de service d'un autre projet, le "projet expéditeur". Cela vous permet de centraliser la gestion des comptes de service dans un projet tout en envoyant des messages au nom d'autres projets. Pour savoir comment procéder, suivez les étapes ci-dessous :

  1. Dans le projet émetteur, assurez-vous que l'API Firebase Cloud Messaging est activée. Vérifiez qu'il est activé dans la console Firebase en accédant à Paramètres > Général. Cliquez ensuite sur l'onglet Cloud Messaging.

  2. Dans le projet émetteur, créez un compte de service.

  3. Dans le projet cible, attribuez le rôle Administrateur de l'API Firebase Cloud Messaging à l'adresse e-mail du compte de service. Pour ce faire, accédez à la page IAM et administration > IAM de la console Google Cloud. Ce rôle permet au compte de service du projet émetteur d'envoyer des messages au projet cible.

  4. Générez un jeton d'accès OAuth 2.0 pour le compte de service du projet émetteur. Pour ce faire, utilisez l'une des options suivantes :

    • Télécharger et utiliser le fichier JSON de clé de compte de service.
    • Utiliser Workload Identity si votre service s'exécute sur Google Cloud.

  5. Utilisez le jeton d'accès obtenu dans l'en-tête Authorization de votre requête d'envoi. La requête doit être envoyée au point de terminaison HTTP v1 du projet cible :

      POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send

Envoyer des messages à des appareils spécifiques

Pour envoyer un message à un seul appareil spécifique, transmettez le jeton d'enregistrement de l'appareil comme indiqué.

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

Commande cURL :

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

En cas de réussite, la réponse de l'API HTTP v1 est un objet JSON contenant l'ID du message :

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

Envoyer un message de notification de test à l'aide de l'API FCM HTTP v1

Cette section explique comment envoyer un message de notification de test à l'aide de l'API FCM HTTP v1.

URL de la requête HTTP

La requête consiste en une requête HTTP POST adressée à la cible spécifiée (un jeton d'enregistrement, un sujet ou une condition) à l'URL suivante :

POST https://fcm.googleapis.com/v1/projectId/messages:send

Exemple de requête HTTP JSON complète

Voici un exemple complet illustrant comment publier une notification dans une requête HTTP POST :

{
  "message": {
    "token": REGISTRATION_TOKEN,
    "notification": {
      "title": "FCM API test",
      "body": "This is the body of the notification.",
      "image": "https://firebase.google.com/static/images/products/cloud-messaging/cloud-messaging-hero_1x.png"
    }
  }
}

Exécuter

Cliquez sur Exécuter pour tester l'exemple dans APIs Explorer.