Invia un messaggio utilizzando l'API HTTP v1 di FCM

Utilizzando l'FCMAPI HTTP v1, puoi creare richieste di messaggi e inviarle a questi tipi di target:

  • Nome argomento
  • Condizione
  • Token di registrazione del dispositivo
  • Nome gruppo di dispositivi (solo protocollo)

Puoi inviare messaggi con un payload di notifica composto da campi predefiniti, un payload di dati dei tuoi campi definiti dall'utente o un messaggio contenente entrambi i tipi di payload. Per ulteriori informazioni, consulta Tipi di messaggi.

Autorizzare le richieste di invio HTTP v1

A seconda dei dettagli dell'ambiente server, utilizza una combinazione di queste strategie per autorizzare le richieste del server ai servizi Firebase:

  • Credenziali predefinite dell'applicazione Google (ADC)
  • Un file JSON dell'account di servizio
  • Un token di accesso OAuth 2.0 di breve durata derivato da un account di servizio

Se la tua applicazione è in esecuzione su Compute Engine, Google Kubernetes Engine, App Engine, o Cloud Functions (inclusi Cloud Functions for Firebase), utilizza le Credenziali predefinite dell'applicazione (ADC). ADC utilizza il service account predefinito esistente per ottenere le credenziali per autorizzare le richieste e consente test locali flessibili tramite la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS. Per un'automazione completa del flusso di autorizzazione, utilizza ADC insieme alle librerie server dell'SDK Admin.

Se la tua applicazione è in esecuzione in un ambiente server non Google, dovrai scaricare un file JSON del service account dal tuo progetto Firebase. Se hai accesso a un file system contenente il file della chiave privata, puoi utilizzare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS per autorizzare le richieste con queste credenziali ottenute manualmente. Se non hai accesso a questi file, devi fare riferimento al file del service account nel codice, operazione da eseguire con estrema attenzione a causa del rischio di esporre le credenziali.

Fornire le credenziali utilizzando ADC

Le Credenziali predefinite dell'applicazione Google (ADC) controllano le credenziali nel seguente ordine:

  1. ADC verifica se la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS è impostata. Se la variabile è impostata, ADC utilizza il file del service account a cui fa riferimento la variabile.

  2. Se la variabile di ambiente non è impostata, ADC utilizza il service account predefinito fornito da Compute Engine, Google Kubernetes Engine, App Engine, e Cloud Functions per le applicazioni in esecuzione su questi servizi.

  3. Se ADC non può utilizzare nessuna delle credenziali precedenti, il sistema genera un errore.

Il seguente esempio di codice dell'SDK Admin illustra questa strategia. L'esempio non specifica esplicitamente le credenziali dell'applicazione. Tuttavia, ADC è in grado di trovare implicitamente le credenziali a condizione che la variabile di ambiente sia impostata o che l'applicazione sia in esecuzione su Compute Engine, Google Kubernetes Engine, App Engine, o 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()

Vai

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

C#

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

Fornire le credenziali manualmente

I progetti Firebase supportano i service account Google, che puoi utilizzare per chiamare le API server Firebase dal server dell'app o dall'ambiente attendibile. Se stai sviluppando codice localmente o eseguendo il deployment della tua applicazione on-premise, puoi utilizzare le credenziali ottenute utilizzando questo service account per autorizzare le richieste del server.

Puoi visualizzare tutti i service account del tuo progetto Firebase nella scheda delle impostazioni > Service account.

Per autenticare un service account e autorizzarlo ad accedere ai servizi Firebase, devi generare un file della chiave privata in formato JSON.

Per generare un file della chiave privata per il tuo service account:

  1. Nella console Firebase, vai alla scheda Impostazioni > Service account.

  2. Fai clic su Genera nuova chiave privata, quindi conferma facendo clic su Genera chiave.

  3. Archivia in modo sicuro il file JSON contenente la chiave.

Quando autorizzi tramite un service account, hai due opzioni per fornire le credenziali alla tua applicazione. Puoi impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS oppure puoi passare esplicitamente il percorso della chiave del service account nel codice. La prima opzione è più sicura ed è vivamente consigliata.

Per impostare la variabile di ambiente:

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave del service account. Questa variabile si applica solo alla sessione di shell corrente, quindi se apri una nuova sessione, imposta di nuovo la variabile.

Linux o macOS

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

Windows

Con PowerShell:

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

Dopo aver completato i passaggi precedenti, le Credenziali predefinite dell'applicazione (ADC) sono in grado di determinare implicitamente le tue credenziali, consentendoti di utilizzare le credenziali del service account durante i test o l'esecuzione in ambienti non Google.

Utilizzare le credenziali per generare token di accesso

A meno che tu non stia utilizzando il Firebase Admin SDK, che gestisce automaticamente l'autorizzazione, dovrai generare il token di accesso e aggiungerlo alle richieste di invio.

Utilizza le credenziali Firebase insieme a Google Auth Library per la lingua che preferisci per recuperare un token di accesso OAuth 2.0 di breve durata:

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

In questo esempio, la libreria client API di Google autentica la richiesta con un token web JSON o JWT. Per ulteriori informazioni, consulta Token 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
messaging.py

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

Una volta scaduto il token di accesso, il metodo di aggiornamento del token viene chiamato automaticamente per recuperare un token di accesso aggiornato.

Per autorizzare l'accesso a FCM, richiedi l'ambito https://www.googleapis.com/auth/firebase.messaging.

Per aggiungere il token di accesso a un'intestazione della richiesta HTTP:

Aggiungi il token come valore dell'intestazione Authorization nel formato Authorization: Bearer <access_token>:

Node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

Python

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

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;
FirebaseMessagingSnippets.java

Autorizzare un service account da un altro progetto

Puoi inviare messaggi per un progetto, il "progetto di destinazione", utilizzando un token OAuth 2.0 generato da un service account in un altro progetto, il "progetto mittente". In questo modo puoi centralizzare la gestione dei service account in un unico progetto durante l'invio di messaggi per conto di altri. Per scoprire come fare, segui questi passaggi:

  1. Nel progetto mittente, assicurati che l'API Firebase Cloud Messaging sia abilitata. Verifica se è abilitata nella Firebase console andando a Impostazioni > Generali. Quindi, fai clic sulla scheda **Cloud Messaging**.

  2. Nel progetto mittente, crea un service account.

  3. Nel progetto di destinazione, assegna il ruolo Amministratore dell'API Firebase Cloud Messaging all'indirizzo email del service account. Puoi farlo nella pagina IAM e amministrazione > IAM della console Google Cloud. Questo ruolo consente al service account del progetto mittente di inviare messaggi al progetto di destinazione.

  4. Genera un token di accesso OAuth 2.0 per il service account nel progetto mittente. Puoi farlo utilizzando una delle seguenti opzioni:

    • Scaricare e utilizzare il file JSON della chiave del service account.
    • Utilizzare Workload Identity se il servizio è in esecuzione su Google Cloud.

  5. Utilizza il token di accesso ottenuto nell'intestazione Authorization della richiesta di invio. La richiesta deve essere inviata all'endpoint HTTP v1 per il progetto di destinazione:

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

Inviare messaggi a dispositivi specifici

Per inviare a un singolo dispositivo specifico, passa il token di registrazione del dispositivo come mostrato.

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

Comando 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

In caso di esito positivo, la risposta dell'API HTTP v1 è un oggetto JSON contenente l'ID del messaggio:

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

Inviare un messaggio di notifica di test utilizzando l'API HTTP v1 di FCM

Questa sezione descrive come inviare un messaggio di notifica di test utilizzando l'API HTTP v1 di FCM.

URL della richiesta HTTP

La richiesta consiste in un POST HTTP al target specificato (un token di registrazione, un argomento o una condizione) al seguente URL:

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

Esempio JSON della richiesta HTTP completa

Di seguito è riportato un esempio completo che mostra come pubblicare una notifica all'interno di una richiesta POST HTTP:

{
  "message": {
    "token": REGISTRATION_TOKEN,
    "notification": {
      "title": "FCM API test",
      "body": "This is the body of the notification.",
      "image": "https://cat.10515.net/1.jpg"
    }
  }
}

Esegui

Fai clic su Esegui per provare l'esempio in Explorer API.