Язык: HTML | XAML

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

Applies to Windows and Windows Phone

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

ПараметрОбязательный/По выборуОписание
grant_typeОбязательныйНеобходимо установить значение "client_credentials".
client_idОбязательныйИдентификатор безопасности (SID) пакета для облачной службы в соответствии с назначением при регистрации вашего приложения в Магазине Windows.
client_secretОбязательныйСекретный ключ для облачной службы в соответствии с назначением при регистрации вашего приложения в Магазине Windows.
scopeОбязательныйНеобходимо установить следующие значения:
  • Windows: "notify.windows.com"
  • Windows Phone: "notify.windows.com" или "s.notify.live.net"

 

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

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

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

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

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

 

Код ответа

Код ответа HTTPОписание
200 OKЗапрос успешный.
400 Bad RequestПроверка подлинности не пройдена. Параметры ответов см. в проекте документа RFC OAuth.

 

Пример

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


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

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

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

Имя заголовкаОбязательный/По выборуОписание
AuthorizationОбязательныйСтандартный заголовок HTTP-авторизации, используемый для проверки подлинности вашего запроса уведомления. В этом заголовке ваша облачная служба предоставляет маркер доступа.
Content-TypeОбязательныйСтандартный заголовок HTTP-авторизации. Для всплывающих уведомлений, уведомлений на плитках и уведомлений на индикаторах событий необходимо установить заголовок "text/xml". Для необработанных уведомлений необходимо установить заголовок "application/octet-stream".
Content-LengthОбязательныйСтандартный заголовок HTTP-авторизации для обозначения размера полезных данных в запросе.
X-WNS-TypeОбязательныйОпределяет тип уведомления в полезных данных: плитка, всплывающее, индикатор события или необработанное.
X-WNS-Cache-PolicyПо выборуВключает и отключает кэширование уведомлений. Этот заголовок применяется только к уведомлениям на плитках, уведомлениям на индикаторах событий и необработанным уведомлениям.
X-WNS-RequestForStatusПо выборуЗапрашивает состояние устройства и состояние подключения WNS в ответе на запрос уведомления.
X-WNS-TagПо выборуСтрока используется для предоставления уведомления с идентифицирующей меткой, применяемой для плиток, которые поддерживают очередь уведомлений. Этот заголовок применяется только к уведомлениям на плитках.
X-WNS-TTLПо выборуЦелое число, выраженное в секундах, которое указывает срок жизни пакетов (TTL).
X-WNS-SuppressPopupПо выборуТолько для Windows Phone: отправляет всплывающее уведомление непосредственно в центр поддержки, не отображая само уведомление на экране.
X-WNS-GroupПо выборуТолько для Windows Phone: используется с заголовком X-WNS-Tag для группировки уведомлений в центре поддержки.
X-WNS-MatchТребуется в зависимости от ситуацииТолько для Windows Phone: требуется для определения целей при удалении всплывающего уведомления из центра поддержки с помощью метода HTTP DELETE.

 

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

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

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


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

 

X-WNS-RequestForStatus

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

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

 

X-WNS-Tag

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

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

  • Applies to Windows Phone

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

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

 

X-WNS-TTL

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

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

X-WNS-TTL: <integer value>
ЗначениеОписание
целое числоСрок жизни уведомления в секундах после получения запроса WNS.

 

X-WNS-SuppressPopup

  • Applies to Windows Phone

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

X-WNS-SuppressPopup: true | false
ЗначениеОписание
trueОтправляет всплывающее уведомление непосредственно в центр поддержки без вызова пользовательского интерфейса уведомления.
falseПо умолчанию. Вызывает пользовательский интерфейс всплывающего уведомления и добавляет уведомление в центр поддержки.

 

X-WNS-Group

  • Applies to Windows Phone

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

X-WNS-Group: <string value>
ЗначениеОписание
Строковый параметрБуквенно-цифровая строка длиной не более 16 символов.

 

X-WNS-Match

  • Applies to Windows Phone

Используется вместе с методом 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
ЗначениеОписание
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-DeviceConnectionStatusПо выборуСостояние устройства, возвращаемое только при наличии соответствующей команды в запросе на уведомления в заголовке X-WNS-RequestForStatus.
X-WNS-Error-DescriptionПо выборуСтрока ошибки в читаемой форме, которую следует регистрировать для проведения отладки.
X-WNS-Msg-IDПо выборуУникальный идентификатор уведомления, используется для целей отладки. При отправке отчета о проблеме эти сведения необходимо регистрировать, чтобы использовать при диагностике.
X-WNS-StatusПо выборуОбозначает успешное получение и обработку уведомления WNS. При отправке отчета о проблеме эти сведения необходимо регистрировать, чтобы использовать при диагностике.

 

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
ЗначениеОписание
connectedУстройство в сети и подключено к WNS.
disconnectedУстройство вне сети и не подключено к WNS.
tempconnectedУстройство временно потеряло связь с WNS, например, при сбросе соединения в 3G-сети или выключении кнопки беспроводного модема на ноутбуке. Платформа клиента уведомлений рассматривает это как временный сбой, а не преднамеренное выключение.

 

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>
ЗначениеОписание
Строковый параметрБуквенно-цифровая строка длиной не более 16 символов.

 

X-WNS-Status

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

X-WNS-Status: received | dropped | channelthrottled
ЗначениеОписание
receivedУведомление получено и обработано WNS.

Примечание  Это не гарантирует, что устройство получило уведомление.

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

 

Коды ответа

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

Код ответа HTTPОписаниеРекомендуемое действие
200 ОКУведомление принято WNS.Не требуется.
400 Bad RequestОдин или несколько заголовков указаны неправильно или конфликтуют с другим заголовком.Зарегистрируйте сведения о запросе. Проверьте запрос и сравните с данным документом.
401 UnauthorizedОблачная служба не представила действительный билет проверки подлинности. Билет OAuth может быть недействительным.Запросить действительный маркер доступа путем проверки подлинности облачной службы с использованием запроса маркера доступа.
403 ForbiddenОблачная служба не авторизована для отправки уведомления в этот универсальный код ресурса (URI), даже если проверка выполнена.Маркер доступа, представленный в запросе, не соответствует учетным данным приложения, направившего запрос на универсальный код ресурса (URI) канала. Убедитесь, что имя пакета в манифесте приложения соответствует учетным данным, присвоенным вашему приложению в информационной панели.
404 Not FoundУниверсальный код ресурса (URI) канала недопустим или не распознан WNS.Зарегистрируйте сведения о запросе. Не отправляйте дополнительные уведомления в этот канал; направляемые на этот адрес уведомления будут отклонены.
405 Method Not AllowedНедопустимый метод (GET, CREATE); разрешен только метод POST (Windows или Windows Phone) либо DELETE (только Windows Phone).Зарегистрируйте сведения о запросе. Перейдите на использование HTTP POST.
406 Not AcceptableОблачная служба превысила свой пределе регулирования.Зарегистрируйте сведения о запросе. Уменьшите скорость отправки уведомлений.
410 GoneСрок действия канала истек.Зарегистрируйте сведения о запросе. Не отправляйте дальнейшие уведомления в этот канал. Приложение должно запросить универсальный код ресурса (URI) для нового канала.
413 Request Entity Too LargeПолезная нагрузка уведомления превышает предельный размер 5 000 байт.Зарегистрируйте сведения о запросе. Проверьте полезную нагрузку, чтобы обеспечить ее соответствие ограничению по размерам.
500 Internal Server ErrorВнутренняя ошибка привела к сбою в доставке уведомления.Зарегистрируйте сведения о запросе. Отправьте отчет об этой проблеме через форумы разработчиков.
503 Service UnavailableСервер в настоящее время недоступен.Зарегистрируйте сведения о запросе. Отправьте отчет об этой проблеме через форумы разработчиков.

 

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

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

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

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

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

Краткое руководство: отправка push-уведомлений
Руководство и контрольный список для push-уведомлений
Проверка подлинности с помощью службы push-уведомлений Windows (WNS)
Запрос, создание и сохранение канала уведомлений
Push-уведомления и периодические уведомления
Обзор WNS

 

 

Показ:
© 2014 Microsoft