Заголовки запросов и ответов службы 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/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 Телефон вы можете отключить пользовательский интерфейс всплывающего уведомления, а не отправлять уведомление непосредственно в центр уведомлений. Это позволяет доставить уведомление автоматически, потенциально превосходный вариант для менее срочных уведомлений. Этот заголовок является необязательным и используется только в каналах Windows Телефон. Если этот заголовок включен в канал Windows, уведомление будет удалено, и вы получите ответ об ошибке от WNS.
X-WNS-SuppressPopup: true | Ложных
| значение | Описание |
|---|---|
| true | Отправьте всплывающее уведомление непосредственно в центр уведомлений; не вызывает всплываемого пользовательского интерфейса. |
| false | По умолчанию. Вызов всплывающего пользовательского интерфейса, а также добавление уведомления в центр уведомлений. |
X-WNS-Group
Примечание.
Центр уведомлений для приложений Магазина Windows Телефон может отображать несколько всплывающих уведомлений с одинаковым тегом, только если они помечены как принадлежащие разным группам. Например, рассмотрим приложение книги рецептов. Каждый рецепт будет определяться тегом. Тост, содержащий комментарий к этому рецепту, будет иметь тег рецепта, но метку группы комментариев. Тост, содержащий рейтинг для этого рецепта, снова будет иметь этот тег рецепта, но будет иметь метку группы рейтингов. Эти разные метки групп позволяют одновременно отображать уведомления о всплывающих уведомлениях в центре уведомлений. Это необязательный заголовок.
X-WNS-Group: <string value>
| значение | Описание |
|---|---|
| строковое значение | Буквенно-цифровые строки не более 16 символов. |
X-WNS-Match
Примечание.
Используется с методом HTTP DELETE для удаления определенного всплывающего уведомления, набора точек (по тегу или группе) или всех всплывающих точек из центра уведомлений для приложений Магазина Windows Телефон. Этот заголовок может указать группу, тег или оба. Этот заголовок необходим в запросе на уведомление 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-Device Подключение ionStatus | 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-Device Подключение ionStatus
Этот заголовок возвращает состояние устройства вызывающему приложению, если он запрашивается в заголовке X-WNS-RequestForStatus запроса на уведомление.
X-WNS-Device Подключение ionStatus: подключен | отключен | 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 Телефон) или DELETE (только Windows Телефон). | Зайдите в журнал сведения о запросе. Переключитесь на использование 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, так как это представляет задержку при отправке уведомления.
Windows developer
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по