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

[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. При разработке приложений для Windows 10 см. раздел последняя документация]

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

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

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

В этом разделе описаны параметры запроса и ответа, используемые при проверке подлинности с помощью службы push-уведомлений Windows (WNS).

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

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

https://login.live.com/accesstoken.srf

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

Облачная служба отправляет эти обязательные параметры в теле 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"
 }

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

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

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

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

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

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

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

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

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

Authorization

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

Синтаксис следующий: строковый литерал "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 кэширует один индикатор событий и одно уведомление на плитке для каждого приложения. Если для приложения включен циклический повтор уведомления, WNS кэширует до пяти уведомлений на плитках. По умолчанию необработанные уведомления не кэшируются, но если кэширование необработанных уведомлений включено, то кэшируется одно необработанное уведомление. Элементы не сохраняются в кэше бесконечно и сбрасываются по истечении разумного периода времени. В противном случае кэшированное содержимое доставляется при следующем подключении устройства к сети.

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

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

X-WNS-RequestForStatus

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

X-WNS-RequestForStatus: true | false

X-WNS-Tag

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

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

Примечание  Для универсальных приложений Windows Phone заголовок X-WNS-Tag можно использовать с заголовком X-WNS-Group, чтобы отображать в центре уведомлений несколько уведомлений с одним и тем же тегом.

X-WNS-Tag: <string value>

X-WNS-TTL

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

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

X-WNS-TTL: <integer value>

X-WNS-SuppressPopup

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

X-WNS-SuppressPopup: true | false

X-WNS-Group

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

X-WNS-Group: <string value>

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;all

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

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

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

X-WNS-Debug-Trace

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

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

X-WNS-DeviceConnectionStatus

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

X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected

X-WNS-Error-Description

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

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

X-WNS-Msg-ID

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

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

X-WNS-Status

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

X-WNS-Status: received | dropped | channelthrottled

Коды ответа

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

Подробную информацию о диагностике, связанную с определенными кодами отклика, см. в разделе об устранении неполадок с уведомлением на плитке, всплывающим уведомлением и уведомлением индикатора событий. См. также: COM Error Codes (WPN, MBN, P2P, Bluetooth).

Неподдерживаемые возможности HTTP

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

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

Связанные разделы

Краткое руководство: отправка push-уведомлений

Руководство и контрольный список для push-уведомлений

Проверка подлинности с помощью службы push-уведомлений Windows (WNS)

Запрос, создание и сохранение канала уведомлений

Push-уведомления и периодические уведомления

Обзор WNS