Заголовки запросов и ответов службы 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-адресу.

Ответ токена доступа

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

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

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

Код ответа

Пример

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

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

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

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

Важные заметки

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

Авторизация

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

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

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

Authorization: Bearer <access-token>

X-WNS-Type

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

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw

X-WNS-Cache-Policy

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

X-WNS-Cache-Policy: cache | no-cache

X-WNS-RequestForStatus

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

    X-WNS-RequestForStatus: true | false

X -WNS-Tag

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

    X-WNS-Tag: <string value>

X-WNS-TTL

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

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

Х-WNS-TTL: <integer value>

X -WNS-SuppressPopup

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

X-WNS-Group

Группа X-WNS: <string value>

X-WNS-Match

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; все

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

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

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

X-WNS-Debug-Trace

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

X-WNS-Отладка-Трассировка: <string value>

X-WNS-DeviceConnectionStatus

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

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

X-WNS-Error-Description

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

x-wns-описание-ошибки: <string value>

X-WNS-Msg-ID

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

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

X-WNS-Status

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

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

MS-CV

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

МС-КВ: <string value>

Коды ответа

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

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

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

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