Переход с устаревших API FCM на HTTP v1

Приложениям, использующим устаревшие API FCM для HTTP и XMPP, следует как можно скорее перейти на API HTTP v1. Отправка сообщений (включая сообщения от исходящих источников) с помощью этих API была прекращена 20 июня 2023 года, а прекращение поддержки начнется 22 июля 2024 года .

Узнайте больше о конкретных затронутых функциях .

Помимо постоянной поддержки и новых функций, API HTTP v1 обладает следующими преимуществами по сравнению с устаревшими API:

  • Повышенная безопасность благодаря токенам доступа. В соответствии с моделью безопасности OAuth2, API HTTP v1 использует кратковременные токены доступа. В случае, если токен доступа становится общедоступным, его можно использовать в злонамеренных целях только в течение часа или около того, после чего он истекает. Токены обновления передаются реже, чем ключи безопасности, используемые в устаревшем API, поэтому вероятность их перехвата значительно ниже.

  • Более эффективная настройка сообщений на разных платформах. Для тела сообщения API HTTP v1 имеет общие ключи, которые отправляются всем целевым экземплярам, ​​а также ключи, специфичные для каждой платформы, которые позволяют настраивать сообщение на разных платформах. Это позволяет создавать «переопределения», которые отправляют немного отличающиеся данные на разные клиентские платформы в одном сообщении.

  • Более расширяемый и перспективный для новых версий клиентских платформ API HTTP v1 полностью поддерживает параметры обмена сообщениями, доступные на платформах Apple, Android и Web. Поскольку каждая платформа имеет свой собственный определенный блок в полезной нагрузке JSON, FCM может расширять API для новых версий и новых платформ по мере необходимости.

Обновите конечную точку сервера.

URL-адрес конечной точки для API HTTP v1 отличается от URL-адреса устаревшей конечной точки следующим образом:

  • Он имеет версионный список, в пути указан /v1 .
  • Указанный путь содержит идентификатор проекта Firebase для вашего приложения в формате /projects/myproject-ID/ . Этот идентификатор доступен на вкладке «Общие настройки проекта» в консоли Firebase .
  • В нем явно указано, что метод send должен быть указан как :send .

Чтобы обновить конечную точку сервера для HTTP v1, добавьте следующие элементы в заголовок ваших запросов на отправку.

HTTP-запросы перед 

POST https://fcm.googleapis.com/fcm/send

Запросы XMPP перед

Устаревшие сообщения XMPP передаются по соединению к следующей конечной точке:

fcm-xmpp.googleapis.com:5235

После 

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

Обновить авторизацию запросов на отправку.

Вместо строки ключа сервера, используемой в устаревших запросах, запросы на отправку HTTP v1 требуют токена доступа OAuth 2.0. Если вы используете Admin SDK для отправки сообщений, библиотека обрабатывает токен за вас. Если вы используете необработанный протокол, получите токен, как описано в этом разделе, и добавьте его в заголовок как Authorization: Bearer <valid Oauth 2.0 token> .

До 

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

После 

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

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

  • Учетные данные приложения Google по умолчанию (ADC)
  • JSON-файл учетной записи службы
  • Кратковременный токен доступа OAuth 2.0, полученный из учетной записи службы.

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

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

Предоставьте учетные данные с помощью ADC.

Проверка учетных данных по умолчанию в приложении Google (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)
}
init.go

C# 

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

Введите учетные данные вручную.

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

Для аутентификации учетной записи службы и предоставления ей доступа к сервисам 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"

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

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

Используйте свои учетные данные 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);
    });
  });
}
index.js

В этом примере клиентская библиотека 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
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

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

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

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

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

Обновите полезную нагрузку запросов на отправку.

В FCM HTTP v1 внесены существенные изменения в структуру полезной нагрузки JSON-сообщений. В первую очередь, эти изменения гарантируют корректную обработку сообщений при получении на разных клиентских платформах; кроме того, они предоставляют дополнительную гибкость в настройке или «переопределении» полей сообщения для каждой платформы.

Помимо изучения примеров в этом разделе, ознакомьтесь с разделом «Настройка сообщения на разных платформах» и просмотрите справочник API , чтобы лучше понять протокол HTTP v1.

Пример: простое уведомление

Здесь представлено сравнение очень простого набора данных уведомления, содержащего только поля title , body и data , демонстрирующее принципиальные различия между устаревшими и HTTP-версиями v1.

До 

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

После 

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

Пример: вложенные данные JSON

В отличие от устаревшего API обмена сообщениями, API HTTP v1 не поддерживает вложенные значения JSON в поле data . Требуется преобразование из JSON в строку.

До 

{
  ...
  "data": {
    "keysandvalues": {"key1": "value1", "key2": 123}
  }
}

После 

{
  "message": {
   ...
    "data": {
      "keysandvalues": "{\"key1\": \"value1\", \"key2\": 123}"
    }
  }
}

Пример: таргетирование на несколько платформ.

Для обеспечения возможности таргетирования на несколько платформ устаревший API выполнял переопределения на бэкэнде. В отличие от него, HTTP v1 предоставляет блоки ключей, специфичные для каждой платформы, которые делают любые различия между платформами явными и видимыми для разработчика. Это позволяет всегда таргетировать несколько платформ одним запросом, как показано в следующем примере.

До 

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

После 

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

Пример: настройка с помощью переопределений платформы.

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

До 

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

После 

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

Пример: нацеливание на конкретные устройства

Для использования API HTTP v1 с конкретными устройствами укажите текущий регистрационный токен устройства в ключе token вместо ключа to .

До 

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

После 

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

Дополнительные примеры и информация об API FCM HTTP v1 доступны по следующим ссылкам: