Справочник по серверу

Реализация сервера не является обязательной. Используйте службу идентификатора экземпляра, если вы хотите выполнить следующие операции:

Получение информации об экземплярах приложения

Чтобы получить информацию об экземпляре приложения, вызовите службу идентификатора экземпляра в этой конечной точке, предоставив токен экземпляра приложения, как показано:

 https://iid.googleapis.com/iid/info/IID_TOKEN

Параметры

  • Authorization: Bearer <access_token> . Установите этот параметр в шапке. Добавьте недолговечный токен OAuth2 в качестве значения заголовка Authorization . Дополнительные сведения о получении этого токена см. в разделе Предоставление учетных данных вручную .
  • access_token_auth: true . Установите этот параметр в шапке.
  • [необязательно] логические details : установите для этого параметра запроса значение true чтобы получить информацию о подписке на тему FCM (если таковая имеется), связанную с этим токеном. Если не указано, по умолчанию используется значение false .

Результаты

В случае успеха вызов возвращает статус HTTP 200 и объект JSON, содержащий:

  • application — имя пакета, связанное с токеном.
  • authorizedEntity — идентификатор проекта, авторизованный для отправки в токен.
  • applicationVersion — версия приложения.
  • platform — возвращает ANDROID , IOS или CHROME чтобы указать платформу устройства, к которому принадлежит токен.

Если установлен флаг details :

  • rel — отношения, связанные с токеном. Например, список подписок на темы.

Пример GET запроса

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

Пример результата

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "rel":{
    "topics":{
      "topicname1":{"addDate":"2015-07-30"},
      "topicname2":{"addDate":"2015-07-30"},
      "topicname3":{"addDate":"2015-07-30"},
      "topicname4":{"addDate":"2015-07-30"}
    }
  }
}

Создание карт отношений для экземпляров приложения

API идентификатора экземпляра позволяет создавать карты отношений для экземпляров приложений. Например, вы можете сопоставить токен регистрации с темой FCM, подписав экземпляр приложения на эту тему. API предоставляет методы для создания таких отношений как индивидуально, так и массово.

Создайте сопоставление отношений для экземпляра приложения.

Имея регистрационный токен и поддерживаемую связь, вы можете создать сопоставление. Например, вы можете подписаться на экземпляр приложения на тему FCM, вызвав службу идентификатора экземпляра в этой конечной точке, предоставив токен экземпляра приложения, как показано:

 https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME

Параметры

  • Authorization: Bearer <access_token> . Установите этот параметр в шапке. Добавьте недолговечный токен OAuth2 в качестве значения заголовка Authorization . Дополнительные сведения о получении этого токена см. в разделе Предоставление учетных данных вручную .
  • access_token_auth: true . Установите этот параметр в шапке.

Результаты

В случае успеха вызов возвращает статус HTTP 200.

Пример POST запроса

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

Пример результата

HTTP 200 OK
{}

Управление картами отношений для нескольких экземпляров приложения

Используя пакетные методы службы идентификатора экземпляра, вы можете выполнять пакетное управление экземплярами приложений. Например, вы можете выполнить массовое добавление или удаление экземпляров приложения в тему FCM. Чтобы обновить до 1000 экземпляров приложения за один вызов API, вызовите службу идентификатора экземпляра в этой конечной точке, предоставив токены экземпляра приложения в теле JSON:

 https://iid.googleapis.com/iid/v1:batchAdd

 https://iid.googleapis.com/iid/v1:batchRemove

Параметры

  • Authorization: Bearer <access_token> . Установите этот параметр в шапке. Добавьте недолговечный токен OAuth2 в качестве значения заголовка Authorization . Дополнительные сведения о получении этого токена см. в разделе Предоставление учетных данных вручную .
  • access_token_auth: true . Установите этот параметр в шапке.
  • to : Название темы.
  • registration_tokens : массив токенов IID для экземпляров приложения, которые вы хотите добавить или удалить.

Результаты

В случае успеха вызов возвращает статус HTTP 200. Пустые результаты указывают на успешную подписку на токен. Для неудачных подписок результат содержит один из следующих кодов ошибок:

  • NOT_FOUND — токен регистрации был удален или приложение удалено.
  • INVALID_ARGUMENT — предоставленный токен регистрации недействителен для идентификатора отправителя.
  • ВНУТРЕННИЙ — Внутренний сервер вышел из строя по неизвестным причинам. Повторите запрос.
  • Too_MANY_TOPICS — Чрезмерное количество тем на экземпляр приложения.
  • RESOURCE_EXHAUSTED — Слишком много запросов на подписку или отмену подписки за короткий период времени. Повторите попытку с экспоненциальной задержкой.

Пример POST запроса

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
{
   "to": "/topics/movies",
   "registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}

Пример результата

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

Создайте регистрационные токены для токенов APN.

Используя метод batchImport службы Instance ID, вы можете массово импортировать существующие токены APN iOS в Firebase Cloud Messaging, сопоставляя их с действительными регистрационными токенами. Вызовите службу идентификатора экземпляра в этой конечной точке, предоставив список токенов APN в теле JSON:

 https://iid.googleapis.com/iid/v1:batchImport

Тело ответа содержит массив регистрационных токенов идентификатора экземпляра, готовых к использованию для отправки сообщений FCM на соответствующий токен устройства APN.

Параметры

  • Authorization: Bearer <access_token> . Установите этот параметр в шапке. Добавьте недолговечный токен OAuth2 в качестве значения заголовка Authorization . Дополнительные сведения о получении этого токена см. в разделе Предоставление учетных данных вручную .
  • access_token_auth: true . Установите этот параметр в шапке.
  • application : идентификатор пакета приложения.
  • sandbox : логическое значение, обозначающее среду песочницы (TRUE) или производственную среду (FALSE).
  • apns_tokens : массив токенов APN для экземпляров приложения, которые вы хотите добавить или удалить. Максимум 100 токенов на запрос.

Результаты

В случае успеха вызов возвращает статус HTTP 200 и тело результата JSON. Для каждого токена APNs, предоставленного в запросе, список результатов включает в себя:

  • Токен APNs.
  • Статус. Либо ОК, либо сообщение об ошибке, описывающее сбой.
  • Для успешных результатов регистрационный токен, который FCM сопоставляет с токеном APNs.

Пример POST запроса

https://iid.googleapis.com/iid/v1:batchImport
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth:true
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
}

Пример результата

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

Реакции на ошибки

Вызовы API сервера идентификатора экземпляра возвращают следующие коды ошибок HTTP:

  • HTTP status 400 (Bad request) — параметры запроса отсутствуют или недействительны. Проверьте сообщения об ошибках для получения подробной информации.
  • HTTP status 401 (Unauthorized) — неверный заголовок авторизации.
  • HTTP status 403 (Forbidden) — заголовок авторизации не соответствует authorizedEntity .
  • HTTP status 404 (Not found) — неверный путь HTTP или токен IID не найден. Проверьте сообщения об ошибках для получения подробной информации.
  • HTTP status 503 (Service unavailable) — сервис недоступен. Повторите запрос с экспоненциальной отсрочкой.