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

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

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

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

 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 - projectId, которому разрешено отправлять данные для токена.
  • 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, вы можете импортировать существующие токены APNs для iOS в Firebase Cloud Messaging, сопоставив их с действительными регистрационными токенами. Вызовите службу Instance ID по этой конечной точке, предоставив список токенов APNs в теле JSON: 

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

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

Параметры

  • Authorization: Bearer <access_token> . Установите этот параметр в заголовке. Добавьте кратковременный токен OAuth2 в качестве значения заголовка Authorization . Для получения дополнительной информации о получении этого токена см. раздел «Предоставьте учетные данные вручную ».
  • access_token_auth: true . Установите этот параметр в заголовке.
  • application : Идентификатор пакета приложения.
  • sandbox : Логическое значение, указывающее на тестовую среду (TRUE) или производственную (FALSE).
  • apns_tokens : Массив токенов APNs для экземпляров приложений, которые вы хотите добавить или удалить. Максимальное количество токенов на запрос — 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) - сервис недоступен. Повторите запрос с экспоненциальной задержкой.