Enviar uma mensagem usando a API HTTP v1 do FCM

Ao usar a API HTTP v1 do FCM, é possível criar solicitações de mensagens e enviá-las aos tipos de destino a seguir:

  • Nome do tópico
  • Condição
  • Token de registro do dispositivo
  • Nome do grupo de dispositivos (somente protocolo)

O payload de notificação das mensagens enviadas pode ser composto por campos predefinidos, por um payload de dados com seus próprios campos definidos por usuário ou por ambos. Consulte Tipos de mensagens para mais informações.

Autorizar solicitações de envio HTTP v1

Dependendo dos detalhes do seu ambiente de servidor, use uma combinação destas estratégias para autorizar as solicitações do servidor para os serviços do Firebase:

  • Application Default Credentials (ADC) do Google
  • Um arquivo JSON da conta de serviço
  • Um token de acesso OAuth 2.0 de curta duração derivado de uma conta de serviço

Se o aplicativo estiver sendo executado no Compute Engine, Google Kubernetes Engine, App Engine ou Cloud Functions, incluindo o Cloud Functions for Firebase, use o Application Default Credentials (ADC). O ADC usa sua conta de serviço padrão para receber credenciais e autorizar solicitações. Além disso, esse serviço permite testes locais flexíveis usando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Para uma automação mais completa do fluxo de autorização, use o ADC com as bibliotecas de servidor do SDK Admin.

Caso o seu aplicativo esteja sendo executado em um ambiente de servidor que não seja do Google, você precisará fazer o download de um arquivo JSON da conta de serviço do seu projeto do Firebase. Se você tiver acesso a um sistema de arquivos com o arquivo de chave privada, você poderá usar a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para autorizar solicitações com as credenciais recebidas manualmente. Se você não tiver acesso a esse arquivo, será preciso referenciar o arquivo da conta de serviço no seu código. Tenha muito cuidado ao fazer isso, porque há risco de suas credenciais serem expostas.

Fornecer credenciais usando o ADC

O Application Default Credentials (ADC) do Google verifica suas credenciais na seguinte ordem:

  1. O ADC verifica se a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS está configurada. Caso esteja, o arquivo da conta de serviço indicado pela variável será usado.

  2. Se a variável de ambiente não estiver definida, o ADC usará a conta de serviço padrão que Compute Engine, Google Kubernetes Engine, App Engine, e o Cloud Functions fornecem para aplicativos executados nesses serviços.

  3. Se o ADC não puder usar nenhuma das credenciais acima, o sistema emitirá um erro.

O exemplo de código do SDK Admin a seguir ilustra essa estratégia. O exemplo não especifica explicitamente as credenciais do aplicativo. No entanto, o ADC consegue encontrar as credenciais, desde que a variável de ambiente esteja configurada ou o aplicativo esteja em execução no 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)
}
init.go

C#

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

Fornecer credenciais manualmente

Os projetos do Firebase oferecem suporte a contas de serviço do Google, que você pode usar para chamar APIs do servidor do Firebase usando seu servidor de aplicativos ou um ambiente confiável. Se você estiver desenvolvendo código ou implantando o aplicativo localmente, será possível usar credenciais recebidas por essa conta de serviço para autorizar solicitações do servidor.

Para autenticar uma conta de serviço e autorizá-la para acessar os serviços do Firebase, gere um arquivo de chave privada no formato JSON.

Para gerar um arquivo de chave privada da conta de serviço, siga estas etapas:

  1. No console Firebase, abra Configurações > Contas de serviço.

  2. Clique em Gerar nova chave privada e selecione Gerar chave para confirmar.

  3. Armazene com segurança o arquivo JSON que contém a chave.

Ao autorizar usando uma conta de serviço, existem duas opções para fornecer as credenciais ao seu aplicativo. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS ou transmita explicitamente o caminho para a chave da conta de serviço no código. A primeira opção é mais segura e é altamente recomendável.

Para definir a variável de ambiente:

Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, defina a variável novamente.

Linux ou macOS

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

Windows

Com o PowerShell:

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

Depois de concluir as etapas acima, o Application Default Credentials (ADC) pode determinar implicitamente suas credenciais, permitindo que você use as credenciais da conta de serviço ao testar ou executar em ambientes que não são do Google.

Usar credenciais para produzir tokens de acesso

A menos que você esteja usando o Firebase Admin SDK, que gerencia a autorização automaticamente, será necessário gerar o token de acesso e adicioná-lo para enviar solicitações.

Use as credenciais do Firebase com a Biblioteca do Google Auth para sua linguagem preferida e recupere um token de acesso do OAuth 2.0 de curta duração:

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

Neste exemplo, a biblioteca de cliente da API do Google autentica a solicitação com um token JSON da Web ou JWT. Para mais informações, consulte tokens JSON da web.

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

O método de atualização de token é chamado automaticamente para recuperar um token atualizado após o de acesso expirar.

Para autorizar o acesso ao FCM, solicite o escopo https://www.googleapis.com/auth/firebase.messaging.

Para adicionar o token de acesso a um cabeçalho da solicitação HTTP:

Adicione o token como o valor do cabeçalho Authorization no 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

Autorizar com uma conta de serviço de um projeto diferente

É possível enviar mensagens para um projeto (o "projeto de destino") usando um token OAuth 2.0 gerado de uma conta de serviço em outro projeto (o "projeto de envio"). Isso permite centralizar o gerenciamento de contas de serviço em um projeto enquanto envia mensagens em nome de outras pessoas. Para saber como fazer isso, siga estas etapas:

  1. Ativar API: verifique se a API Firebase Cloud Messaging está ativada no projeto do remetente.
  2. Criar conta de serviço: crie uma conta de serviço no projeto do remetente.
  3. Conceder permissões: no projeto de destino, conceda ao endereço de e-mail da conta de serviço o papel de Administrador da API Firebase Cloud Messaging na página do IAM. Isso permite que a conta de serviço do outro projeto envie mensagens para o projeto de destino.
  4. Receber token: gere um token de acesso do OAuth 2.0 para a conta de serviço no projeto do remetente. Para fazer isso, siga uma destas opções:
    • Fazer o download e usar o arquivo JSON da chave da conta de serviço.
    • Ou use a Identidade da carga de trabalho se o serviço estiver sendo executado no Google Cloud.
  5. Enviar solicitação: use o token de acesso obtido no cabeçalho Authorization da sua solicitação de envio. A solicitação precisa ser feita para o endpoint HTTP v1 do projeto de destino: 
        POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send

Enviar mensagens a dispositivos específicos

Para enviar para um único dispositivo específico, transmita o token de registro do dispositivo, conforme mostrado.

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

Se a solicitação for bem-sucedida, a resposta da API HTTP v1 será um objeto JSON que contém o ID da mensagem:

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

Enviar uma mensagem de notificação de teste usando a API HTTP v1 do FCM

Nesta seção, descrevemos como enviar uma mensagem de notificação de teste usando a API HTTP v1 do FCM.

URL de solicitação HTTP

A solicitação consiste em um HTTP POST para o destino especificado (um token de registro, tópico ou condição) no seguinte URL:

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

Exemplo de JSON de solicitação HTTP completa

Confira um exemplo completo de como postar uma notificação em uma solicitação HTTP POST:

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

Executar

Clique em Executar para testar a amostra no APIs Explorer.