Поделиться через

Заголовки запросов и ответов службы push-уведомлений (приложения среда выполнения Windows)

  • Статья

В этом разделе описываются веб-API-интерфейсы службы и протоколы, необходимые для отправки push-уведомления.

Общие сведения о службах push-уведомлений Windows (WNS) см. в концептуальном обсуждении концепций push-уведомлений и WNS, требований и операций.

Запрос и получение маркера доступа

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

Запрос маркера доступа

HTTP-запрос отправляется в WNS для проверки подлинности облачной службы и получения маркера доступа в ответ. Запрос выдается с https://login.live.com/accesstoken.srf помощью протокола SSL.

Параметры запроса маркера доступа

Облачная служба отправляет эти необходимые параметры в тексте HTTP-запроса с помощью формата application/x-www-form-urlencoded. Необходимо убедиться, что все параметры закодированы по URL-адресу.

Параметр Обязательное поле Описание
grant_type TRUE Должен иметь значениеclient_credentials.
client_id TRUE Идентификатор безопасности пакета для облачной службы, назначенный при регистрации приложения в Microsoft Store.
client_secret TRUE Секретный ключ облачной службы, назначенный при регистрации приложения в Microsoft Store.
область TRUE Нужно задать значение notify.windows.com

Ответ маркера доступа

WNS проходит проверку подлинности облачной службы, и в случае успешного выполнения отвечает на запрос "200 ОК", включая маркер доступа. В противном случае WNS отвечает с соответствующим кодом ошибки HTTP, как описано в проекте протокола OAuth 2.0.

Параметры ответа маркера доступа

Маркер доступа возвращается в ответе HTTP, если облачная служба успешно прошел проверку подлинности. Этот маркер доступа можно использовать в запросах уведомлений до истечения срока его действия. В ответе HTTP используется тип носителя application/json.

Параметр Обязательное поле Описание
access_token; TRUE Маркер доступа, используемый облачной службой при отправке уведомления.
token_type FALSE Всегда возвращался как bearer.

Код отклика

Код HTTP-ответа Description
200 OK Запрос выполнен успешно.
400 — недопустимый запрос Сбой проверки подлинности. Дополнительные сведения о параметрах ответа см. в черновике запроса OAuth для комментариев (RFC).

Пример

Ниже показан пример успешного ответа проверки подлинности:

 HTTP/1.1 200 OK   
 Cache-Control: no-store
 Content-Length: 422
 Content-Type: application/json
 
 {
     "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
     "token_type":"bearer",
     "expires_in": 86400
 }

Отправка запроса на уведомление и получение ответа

В этом разделе описываются заголовки, участвующие в HTTP-запросе для WNS для доставки уведомления и тех, кто участвует в ответе.

  • Отправка запроса на уведомление
  • Отправка ответа на уведомление
  • Неподдерживаемые функции HTTP

Отправка запроса на уведомление

При отправке запроса на уведомление вызывающее приложение выполняет HTTP-запрос по протоколу SSL, адресованный универсальному идентификатору ресурса канала (URI). Content-Length — это стандартный заголовок HTTP, который должен быть указан в запросе. Все остальные стандартные заголовки являются необязательными или не поддерживаются.

Кроме того, в запросе уведомления можно использовать заголовки настраиваемых запросов, перечисленные здесь. Некоторые заголовки являются обязательными, а другие — необязательными.

Параметры запроса

Имя заголовка Обязательное поле Описание
Авторизация TRUE Стандартный заголовок авторизации HTTP, используемый для проверки подлинности запроса на уведомление. Облачная служба предоставляет свой маркер доступа в этом заголовке.
Тип контента TRUE Стандартный заголовок авторизации HTTP. Для всплывающих уведомлений, плиток и индикаторов событий этот заголовок должен иметь значение text/xml. Для необработанных уведомлений этот заголовок должен иметь значение application/octet-stream.
content-length: 0 TRUE Стандартный заголовок авторизации HTTP для обозначения размера полезных данных запроса.
X-WNS-Type TRUE Определяет тип уведомления в полезных данных: плитку, всплывающее сообщение, значок или необработанный.
Политика кэша X-WNS FALSE Включает или отключает кэширование уведомлений. Этот заголовок применяется только к плитке, индикатору событий и необработанным уведомлениям.
X-WNS-RequestForStatus FALSE Запрашивает состояние устройства и состояние подключения WNS в ответе на уведомление.
X-WNS-Tag FALSE Строка, используемая для предоставления уведомления с меткой идентификации, используемой для плиток, поддерживающих очередь уведомлений. Этот заголовок применяется только к уведомлениям плитки.
X-WNS-TTL FALSE Целочисленное значение, выраженное в секундах, указывающее время жизни (TTL).
MS-CV FALSE Значение вектора корреляции, используемое для запроса.

Важные примечания

  • Content-Length и Content-Type — это единственные стандартные заголовки HTTP, которые включены в уведомление, доставленное клиенту, независимо от того, были ли в запрос включены другие стандартные заголовки.
  • Все остальные стандартные заголовки HTTP либо игнорируются, либо возвращают ошибку, если функциональность не поддерживается.
  • Начиная с февраля 2023 года WNS кэширует только одно уведомление об плитке, когда устройство находится в автономном режиме.

Авторизация

Заголовок авторизации используется для указания учетных данных вызывающей стороны, следуя методу авторизации OAuth 2.0 для маркеров носителя .

Синтаксис состоит из строкового литерала "Носителя", за которым следует пробел, а затем маркер доступа. Этот маркер доступа извлекается путем выдачи запроса маркера доступа, описанного выше. Этот же маркер доступа можно использовать при последующих запросах уведомлений до истечения срока действия.

Этот заголовок является обязательным.

Authorization: Bearer <access-token>

X-WNS-Type

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

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw
значение Описание
wns/badge Уведомление о создании наложения значка на плитку. Заголовок Content-Type, включенный в запрос на уведомление, должен иметь значение text/xml.
wns/tile Уведомление об обновлении содержимого плитки. Заголовок Content-Type, включенный в запрос на уведомление, должен иметь значение text/xml.
wns/toast Уведомление о вызове всплывающего уведомления на клиенте. Заголовок Content-Type, включенный в запрос на уведомление, должен иметь значение text/xml.
wns/raw Уведомление, которое может содержать пользовательские полезные данные и поставляется непосредственно в приложение. Заголовок Content-Type, включенный в запрос на уведомление, должен иметь значение application/octet-stream.

Политика кэша X-WNS

Если целевое устройство уведомления находится в автономном режиме, WNS будет кэшировать один значок, одну плитку и одно всплывающее уведомление для каждого URI канала. По умолчанию необработанные уведомления не кэшируются, но если кэширование необработанных уведомлений включено, одно необработанное уведомление кэшируется. Элементы не хранятся в кэше на неопределенный срок и будут удалены после разумного периода времени. В противном случае кэшированное содержимое доставляется при следующем подключении устройства к сети.

X-WNS-Cache-Policy: cache | no-cache
значение Описание
cache По умолчанию. Уведомления будут кэшироваться, если пользователь находится в автономном режиме. Это параметр по умолчанию для уведомлений плитки и индикаторов событий.
no-cache Уведомление не будет кэшировано, если пользователь находится в автономном режиме. Это параметр по умолчанию для необработанных уведомлений.

X-WNS-RequestForStatus

Указывает, должен ли ответ включать состояние устройства и состояние подключения WNS. Это необязательный заголовок.

    X-WNS-RequestForStatus: true | false
значение Описание
true Возвращает состояние устройства и состояние уведомления в ответе.
false По умолчанию. Не возвращайте состояние устройства и состояние уведомления.

X-WNS-Tag

Назначает метку тега уведомлением. Тег используется в политике замены плитки в очереди уведомлений, когда приложение выбрало цикл уведомлений. Если уведомление с этим тегом уже существует в очереди, новое уведомление с тем же тегом занимает свое место.

Примечание.

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

    X-WNS-Tag: <string value>
значение Описание
строковое значение Буквенно-цифровые строки не более 16 символов.

X-WNS-TTL

Указывает срок жизни (срок действия) для уведомления. Обычно это не требуется, но его можно использовать, если вы хотите убедиться, что уведомления не отображаются позже определенного времени. TTL указывается в секундах и соответствует времени, когда WNS получает запрос. При указании TTL устройство не будет отображать уведомление после этого времени. Обратите внимание, что это может привести к тому, что уведомление никогда не отображается вообще, если срок жизни слишком короткий. Как правило, время истечения срока действия будет измеряться по крайней мере в минутах.

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

X-WNS-TTL: <integer value>

значение Описание
целочисленное значение Срок действия уведомления в секундах после получения запроса WNS.

X-WNS-SuppressPopup

Примечание.

Для приложений Магазина Windows Phone можно отключить пользовательский интерфейс всплывающего уведомления, а не отправлять уведомление непосредственно в центр уведомлений. Это позволяет доставить уведомление автоматически, потенциально превосходный вариант для менее срочных уведомлений. Этот заголовок является необязательным и используется только в каналах Windows Phone. Если этот заголовок включен в канал Windows, уведомление будет удалено, и вы получите ответ об ошибке от WNS.

X-WNS-SuppressPopup: true | ложный

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

X-WNS-Group

Примечание.

Центр уведомлений для приложений Магазина Windows Phone может отображать несколько всплывающих уведомлений с одинаковым тегом, только если они помечены как принадлежащие разным группам. Например, рассмотрим приложение книги рецептов. Каждый рецепт будет определяться тегом. Тост, содержащий комментарий к этому рецепту, будет иметь тег рецепта, но метку группы комментариев. Тост, содержащий рейтинг для этого рецепта, снова будет иметь этот тег рецепта, но будет иметь метку группы рейтингов. Эти разные метки групп позволяют одновременно отображать уведомления о всплывающих уведомлениях в центре уведомлений. Это необязательный заголовок.

X-WNS-Group: <string value>

значение Описание
строковое значение Буквенно-цифровые строки не более 16 символов.

X-WNS-Match

Примечание.

Используется с методом HTTP DELETE для удаления определенного всплывающего уведомления, набора точек (по тегу или группе) или всех всплывающих точек из центра уведомлений для приложений Магазина Windows Phone. Этот заголовок может указать группу, тег или оба. Этот заголовок необходим в запросе на уведомление HTTP DELETE. Все полезные данные, включенные в этот запрос уведомления, игнорируются.

X-WNS-Match: type:wns/toast; group=<string value>; tag=<string value> | type:wns/toast; group=<string value> | type:wns/toast; tag=<string value> | type:wns/toast; все

значение Описание
type:wns/toast; group=<string value>; tag=<string value> Удалите одно уведомление, помеченное как указанным тегом, так и группой.
type:wns/toast; group=<string value> Удалите все уведомления, помеченные указанной группой.
type:wns/toast; tag=<string value> Удалите все уведомления, помеченные указанным тегом.
type:wns/toast; все Снимите все уведомления приложения из центра уведомлений.

Отправка ответа на уведомление

После обработки запроса на уведомление WNS он отправляет HTTP-сообщение в ответ. В этом разделе рассматриваются параметры и заголовки, которые можно найти в этом ответе.

Параметры ответа

Имя заголовка Обязательное поле Описание
X-WNS-Debug-Trace FALSE Сведения об отладке, которые должны быть зарегистрированы для устранения неполадок при создании отчетов о проблеме.
X-WNS-DeviceConnectionStatus FALSE Состояние устройства возвращается только в том случае, если запрашивается в запросе уведомления через заголовок X-WNS-RequestForStatus.
X-WNS-Error-Description FALSE Строка ошибки, доступной для чтения пользователем, которая должна быть зарегистрирована, чтобы помочь в отладке.
X-WNS-Msg-ID FALSE Уникальный идентификатор уведомления, используемый для отладки. При создании отчетов о проблеме эти сведения должны быть зарегистрированы для устранения неполадок.
Состояние X-WNS FALSE Указывает, успешно ли WNS получил и обработал уведомление. При создании отчетов о проблеме эти сведения должны быть зарегистрированы для устранения неполадок.
MS-CV FALSE Сведения об отладке, которые должны быть зарегистрированы для устранения неполадок при создании отчетов о проблеме.

X-WNS-Debug-Trace

Этот заголовок возвращает полезные сведения об отладке в виде строки. Рекомендуется регистрировать этот заголовок, чтобы помочь разработчикам отладить проблемы. Этот заголовок вместе с заголовком X-WNS-Msg-ID и MS-CV требуется при отправке отчетов о проблеме с WNS.

X-WNS-Debug-Trace: <string value>

значение Описание
строковое значение Буквенно-цифровые строки.

X-WNS-DeviceConnectionStatus

Этот заголовок возвращает состояние устройства вызывающему приложению, если он запрашивается в заголовке X-WNS-RequestForStatus запроса на уведомление.

X-WNS-DeviceConnectionStatus: подключен | отключен | tempdisconnected

значение Описание
подключено Устройство подключено к сети и подключено к WNS.
отключено Устройство находится в автономном режиме и не подключено к WNS.
tempconnected (не рекомендуется) Устройство временно потеряло подключение к WNS, например при удалении подключения 3G или беспроводного коммутатора на ноутбуке. Она рассматривается клиентской платформой уведомлений как временное прерывание, а не преднамеренное отключение.

X-WNS-Error-Description

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

X-WNS-Error-Description: <string value>

значение Описание
строковое значение Буквенно-цифровые строки.

X-WNS-Msg-ID

Этот заголовок используется для предоставления вызывающей стороны идентификатора уведомления. Мы рекомендуем регистрировать этот заголовок, чтобы помочь отладить проблемы. Этот заголовок вместе с X-WNS-Debug-Trace и MS-CV требуются при отправке отчетов о проблеме с WNS.

X-WNS-Msg-ID: <string value>

значение Описание
строковое значение Буквенно-цифровые строки не более 16 символов.

Состояние X-WNS

В этом заголовке описывается, как WNS обрабатывает запрос на уведомление. Это можно использовать, а не интерпретировать коды откликов как успешные или неудачные.

Состояние X-WNS: получено | отброшено | channelthrottled

значение Описание
Получено Уведомление получено и обработано WNS. Примечание. Это не гарантирует, что устройство получило уведомление.
Упал Уведомление было явно удалено из-за ошибки или из-за того, что клиент явно отклонил эти уведомления. Всплывающие уведомления также будут удалены, если устройство находится в автономном режиме.
channelthrottled Уведомление было удалено, так как сервер приложений превысил ограничение скорости для этого конкретного канала.

MS-CV

Этот заголовок предоставляет вектор корреляции, связанный с запросом, который в основном используется для отладки. Если cv предоставляется в рамках запроса, WNS будет использовать это значение, в противном случае WNS создаст и ответит обратно с помощью CV. Этот заголовок вместе с заголовком X-WNS-Debug-Trace и X-WNS-Msg-ID требуются при отправке отчетов о проблеме в WNS.

Внимание

Создайте новое резюме для каждого запроса push-уведомлений, если вы предоставляете собственное резюме.

MS-CV: <string value>

значение Описание
строковое значение Соответствует стандарту вектора корреляции

Коды откликов

Каждое HTTP-сообщение содержит один из этих кодов ответа. WNS рекомендует разработчикам записывать код ответа для использования в отладке. Когда разработчики сообщают о проблеме с WNS, они требуются для предоставления кодов ответов и сведений о заголовках.

Код HTTP-ответа Description Рекомендуемое действие
200 OK Уведомление было принято WNS. Не требуются.
400 — недопустимый запрос Один или несколько заголовков были указаны неправильно или конфликтуют с другим заголовком. Зайдите в журнал сведения о запросе. Проверьте запрос и сравните с этой документацией.
401 — не авторизовано Облачная служба не присутствовала на допустимом запросе проверки подлинности. Билет OAuth может быть недопустимым. Запрос допустимого маркера доступа путем проверки подлинности облачной службы с помощью запроса маркера доступа.
403. Запрещено Облачная служба не авторизована для отправки уведомления в этот универсальный код ресурса (URI), даже если они проходят проверку подлинности. Маркер доступа, предоставленный в запросе, не соответствует учетным данным приложения, запрашивающего URI канала. Убедитесь, что имя пакета в манифесте приложения соответствует учетным данным облачной службы, предоставленным приложению на панели мониторинга.
404 Не найдено Недопустимый URI канала или не распознается WNS. Зайдите в журнал сведения о запросе. Не отправлять дальнейшие уведомления в этот канал; Уведомления по этому адресу завершаются ошибкой.
405 Метод не разрешен Недопустимый метод (GET, CREATE); разрешено только POST (Windows или Windows Phone) или DELETE (только Для Windows Phone). Зайдите в журнал сведения о запросе. Переключитесь на использование HTTP POST.
406 Недопустимый Облачная служба превысила ограничение регулирования. Отправьте запрос после значения заголовка Retry-After в ответе
410 — потеряно Срок действия канала истек. Зайдите в журнал сведения о запросе. Не отправляйте дальнейшие уведомления в этот канал. Запросите новый универсальный код ресурса (URI) канала.
Заблокированный домен 410 Домен отправки заблокирован WNS. Не отправляйте дальнейшие уведомления в этот канал. Домен отправки заблокирован WNS для злоупотреблений push-уведомлениями.
413 — размер запрашиваемой сущности слишком большой Полезные данные уведомления превышают ограничение размера 5000 байтов. Зайдите в журнал сведения о запросе. Проверьте полезные данные, чтобы убедиться, что он находится в пределах ограничений размера.
500 Internal Server Error (внутренняя ошибка сервера). Внутренняя ошибка привела к сбою доставки уведомлений. Зайдите в журнал сведения о запросе. Сообщите об этой проблеме на форумах разработчиков.
503 Сервис недоступен Сервер сейчас недоступен. Зайдите в журнал сведения о запросе. Сообщите об этой проблеме на форумах разработчиков. Если заголовок Retry-After наблюдается, отправьте запрос после значения заголовка Retry-After в ответе.

Неподдерживаемые функции HTTP

Веб-интерфейс WNS поддерживает HTTP 1.1, но не поддерживает следующие функции:

  • Разделение на блоки
  • Конвейеризация (POST не является идемпотентной)
  • Хотя он поддерживается, разработчики должны отключить Ожидает-100, так как это представляет задержку при отправке уведомления.