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

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

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

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

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

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

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

Код ответа

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

Example

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

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

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

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

Имя заголовка	Required	Description
Authorization	TRUE	Стандартный заголовок авторизации HTTP, используемый для проверки подлинности запроса на уведомление. Облачная служба предоставляет свой маркер доступа в этом заголовке.
Content-Type	TRUE	Стандартный заголовок авторизации HTTP. Для тост-уведомлений, плиток и индикаторов событий этот заголовок должен иметь значение text/xml. Для необработанных уведомлений этот заголовок должен иметь значение application/octet-stream.
Content-Length	TRUE	Стандартный заголовок авторизации HTTP для обозначения размера полезных данных запроса.
X-WNS-Type	TRUE	Определяет тип уведомления в полезных данных: плитка, всплывающее сообщение, значок или сырой.
X-WNS-Cache-Policy	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 сохраняет в кэше только одно уведомление о плитке, когда устройство находится в автономном режиме.

Authorization

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

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

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

Authorization: Bearer <access-token>

X-WNS-Type

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

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

Value	Description
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-Cache-Policy

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

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

Value	Description
cache	Default. Уведомления будут кэшироваться, если пользователь находится в автономном режиме. Это параметр по умолчанию для уведомлений тайлов и бэйджей.
no-cache	Уведомление не будет кэшировано, если пользователь находится в автономном режиме. Это параметр по умолчанию для необработанных уведомлений.

X-WNS-RequestForStatus

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

    X-WNS-RequestForStatus: true | false

Value	Description
true	Верните состояние устройства и состояние уведомления в ответе.
false	Default. Не возвращайте состояние устройства и состояние уведомления.

X-WNS-Tag

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

Note

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

    X-WNS-Tag: <string value>

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

X-WNS-TTL

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

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

X-WNS-TTL: <integer value>

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

X-WNS-SuppressPopup

Note

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

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

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

X-WNS-Group

Note

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

X-WNS-Group: <string value>

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

X-WNS-Match

Note

Используется с методом 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; все

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

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

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

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

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

X-WNS-Debug-Trace

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

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

Value	Description
строковое значение	Буквенно-цифровая строка.

X-WNS-DeviceConnectionStatus

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

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

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

X-WNS-Error-Description

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

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

Value	Description
строковое значение	Буквенно-цифровая строка.

X-WNS-Msg-ID

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

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

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

X-WNS-Status

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

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

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

MS-CV

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

Important

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

MS-CV: <string value>

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

Коды ответа

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

Код HTTP-ответа	Description	Рекомендуемое действие
200 OK (Запрос выполнен успешно)	Уведомление было принято WNS.	Не требуется.
400 Недопустимый запрос	Один или несколько заголовков были указаны неправильно или конфликтуют с другим заголовком.	Запишите сведения о вашем запросе. Проверьте запрос и сравните с этой документацией.
401 — не авторизовано	Облачный сервис не представил действительный билет аутентификации. Токен OAuth может быть недействительным.	Запросите действительный токен доступа, аутентифицируя вашу облачную службу с помощью запроса токена доступа.
403 Запрещено	Облачная служба не авторизована для отправки уведомления на этот URI, несмотря на то, что она аутентифицирована.	Маркер доступа, предоставленный в запросе, не соответствует учетным данным приложения, запрашивающего URI канала. Убедитесь, что имя пакета в манифесте приложения соответствует учетным данным облачной службы, предоставленным приложению на панели мониторинга.
404 Не найдено	URI канала недействителен или не распознаётся WNS.	Запишите сведения о вашем запросе. Не отправляйте дальнейшие уведомления в этот канал; уведомления на этот адрес не будут доставлены.
Метод 405 не разрешен	Недопустимый метод (GET, СОЗДАТЬ); разрешено только 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, но не поддерживает следующие функции:

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