Как отправить сообщение с помощью FCM HTTP v1 API

С помощью FCM HTTP v1 API можно создавать запросы сообщений и отправлять их на следующие типы целевых устройств:

  • Название темы
  • Условие
  • Токен регистрации устройства
  • Название группы устройств (поддержка прекращена, будет удалено 29 сентября 2027 г.)

Вы можете отправлять сообщения с полезной нагрузкой уведомления, состоящей из стандартных полей, полезной нагрузкой данных, состоящей из заданных вами полей, или сообщением, содержащим оба типа полезной нагрузки. Подробнее о типах сообщений…

Как авторизовать запросы на отправку HTTP v1

В зависимости от особенностей вашей серверной среды используйте сочетание следующих стратегий для авторизации серверных запросов к сервисам Firebase:

  • Google Application Default Credentials (ADC)
  • JSON-файл сервисного аккаунта.
  • Кратковременный токен доступа OAuth 2.0, полученный из сервисного аккаунта.

Если ваше приложение работает в Compute Engine, Google Kubernetes Engine, App Engine или Cloud Functions (включая Cloud Functions for Firebase), используйте Application Default Credentials (ADC). ADC использует существующий сервисный аккаунт по умолчанию, чтобы получать учетные данные для авторизации запросов, и позволяет гибко тестировать локально с помощью переменной среды GOOGLE_APPLICATION_CREDENTIALS. Чтобы максимально автоматизировать процесс авторизации, используйте ADC вместе с серверными библиотеками Admin SDK.

Если ваше приложение работает в серверной среде, отличной от Google, вам нужно скачать JSON-файл сервисного аккаунта из проекта Firebase. Если у вас есть доступ к файловой системе, содержащей файл закрытого ключа, вы можете использовать переменную среды GOOGLE_APPLICATION_CREDENTIALS для авторизации запросов с этими полученными вручную учетными данными. Если у вас нет доступа к такому файлу, вам нужно указать в коде файл сервисного аккаунта. Это следует делать с особой осторожностью, чтобы не раскрыть свои учетные данные.

Как предоставить учетные данные с помощью ADC

Google Application Default Credentials (ADC) проверяет учетные данные в следующем порядке:

  1. ADC проверяет, задана ли переменная среды GOOGLE_APPLICATION_CREDENTIALS. Если переменная задана, ADC использует файл сервисного аккаунта, на который она указывает.

  2. Если переменная среды не задана, ADC использует сервисный аккаунт по умолчанию, который Compute Engine, Google Kubernetes Engine, App Engine и Cloud Functions предоставляют приложениям, работающим в этих сервисах.

  3. Если ADC не может использовать ни одни из указанных выше учетных данных, система выдает ошибку.

Ниже приведен пример кода Admin SDK, в котором реализована эта стратегия. В примере не указаны учетные данные приложения. Однако ADC может неявно найти учетные данные, если задана переменная среды или если приложение запущено в Compute Engine, Google Kubernetes Engine, App Engine или 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()

Проложить маршрут

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(),
});

Как указать учетные данные вручную

Проекты Firebase поддерживают сервисные аккаунты Google, которые можно использовать для вызова серверных API Firebase с сервера приложения или из доверенной среды. Если вы разрабатываете код локально или развертываете приложение в своей инфраструктуре, то можете использовать учетные данные, полученные с помощью этого сервисного аккаунта, для авторизации запросов к серверу.

Все сервисные аккаунты для вашего проекта Firebase можно посмотреть на вкладке Настройки > Сервисные аккаунты.

Чтобы аутентифицировать сервисный аккаунт и предоставить ему доступ к сервисам Firebase, необходимо создать файл закрытого ключа в формате JSON.

Чтобы создать файл закрытого ключа для сервисного аккаунта:

  1. В консоли Firebase перейдите на вкладку Настройки > Сервисные аккаунты.

  2. Нажмите Generate New Private Key (Создать новый закрытый ключ) и подтвердите действие, нажав Generate Key (Создать ключ).

  3. Надежно сохраните JSON-файл с ключом.

При авторизации через сервисный аккаунт вы можете предоставить приложению учетные данные двумя способами. Вы можете задать переменную среды GOOGLE_APPLICATION_CREDENTIALS или явно передать путь к ключу сервисного аккаунта в коде. Первый вариант более безопасен, и мы настоятельно рекомендуем использовать его.

Чтобы задать переменную среды:

Задайте для переменной среды GOOGLE_APPLICATION_CREDENTIALS путь к JSON-файлу, содержащему ключ сервисного аккаунта. Эта переменная применяется только к текущему сеансу оболочки, поэтому, если вы откроете новый сеанс, вам нужно будет задать переменную снова.

Linux или macOS

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

Windows

С помощью PowerShell:

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

После того как вы выполните описанные выше действия, Application Default Credentials (ADC) смогут неявно определять ваши учетные данные, что позволит вам использовать учетные данные сервисного аккаунта при тестировании или запуске в средах, отличных от Google.

Как использовать учетные данные для создания токенов доступа

Если вы не используете Firebase Admin SDK, который автоматически обрабатывает авторизацию, вам нужно создать токен доступа и добавить его в запросы.

Используйте учетные данные Firebase вместе с библиотекой аутентификации Google на выбранном вами языке, чтобы получить токен доступа OAuth 2.0 с коротким сроком действия:

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);
    });
  });
}

В этом примере клиентская библиотека Google API аутентифицирует запрос с помощью веб-токена JSON (JWT). Дополнительную информацию можно найти в разделе Веб-токены 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();
}

После того как срок действия токена доступа истечет, автоматически вызывается метод обновления токена, чтобы получить новый токен доступа.

Чтобы разрешить доступ к FCM, запросите область действия https://www.googleapis.com/auth/firebase.messaging.

Чтобы добавить токен доступа в заголовок HTTP-запроса:

Добавьте токен в качестве значения заголовка Authorization в следующем формате: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;

Как авторизовать сервисный аккаунт из другого проекта

Вы можете отправлять сообщения для одного проекта (целевого проекта), используя токен OAuth 2.0, сгенерированный из сервисного аккаунта в другом проекте (проекте отправителя). Это позволяет централизованно управлять сервисными аккаунтами в одном проекте, отправляя сообщения от имени других пользователей. Чтобы узнать, как это сделать, выполните следующие действия:

  1. В проекте отправителя убедитесь, что включен Firebase Cloud Messaging API. Проверьте, включена ли она в консоли Firebase. Для этого выберите Настройки > Общие. Затем нажмите на вкладку Обмен сообщениями в облаке.

  2. В проекте отправителя создайте сервисный аккаунт.

  3. В целевом проекте назначьте роль администратора Firebase Cloud Messaging API адресу электронной почты сервисного аккаунта. Это можно сделать на странице IAM в разделе IAM и администрирование консоли Google Cloud. Эта роль позволяет сервисному аккаунту из проекта отправителя отправлять сообщения в целевой проект.

  4. Создайте токен доступа OAuth 2.0 для сервисного аккаунта в проекте отправителя. Это можно сделать одним из следующих способов:

    • Скачивание и использование JSON-файла ключа сервисного аккаунта.
    • Используйте Workload Identity, если ваш сервис работает на платформе Google Cloud.

  5. Используйте полученный токен доступа в заголовке Authorization запроса на отправку. Запрос должен быть отправлен в конечную точку HTTP версии 1 для целевого проекта:

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

Как отправлять сообщения на определенные устройства

Чтобы отправить сообщение на одно определенное устройство, передайте токен регистрации устройства, как показано ниже.

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

Команда 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

При успешном выполнении запроса API HTTP версии 1 возвращает объект JSON, содержащий идентификатор сообщения:

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

Как отправить тестовое уведомление с помощью FCM HTTP v1 API

В этом разделе рассказывается, как отправить тестовое уведомление с помощью FCM HTTP v1 API.

URL HTTP-запроса

Запрос состоит из HTTP-запроса POST к указанной цели (токену регистрации, теме или условию) по следующему URL:

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

Полный образец JSON-запроса HTTP

Ниже приведен полный пример того, как отправить уведомление в 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"
    }
  }
}

Запуск

Нажмите Выполнить, чтобы попробовать пример в API Explorer.