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

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

  • Название темы
  • Условие
  • Токен регистрации устройства
  • Название группы устройств (поддержка прекращена, будет удалено 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, откройте раздел Settings (Настройки) и перейдите на вкладку Service accounts (Сервисные аккаунты).

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

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

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

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

  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"

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

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

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

Используйте учетные данные Firebase вместе с библиотекой Google Auth для выбранного языка, чтобы получить токен доступа 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 адресу электронной почты сервисного аккаунта. Для этого в консоли Google Cloud перейдите в раздел IAM & Admin (IAM и администрирование) > IAM. Эта роль позволяет сервисному аккаунту из проекта-отправителя отправлять сообщения в целевой проект.

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

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

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

      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

В случае успеха ответом HTTP v1 API будет объект 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

Полный пример HTTP-запроса в формате JSON

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