Cabeçalhos de solicitação e resposta de serviço de notificação por push (aplicativos do Tempo de Execução do Windows)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Este tópico descreve os APIs de serviço para serviço Web e os protocolos necessários para enviar uma notificação por push.

Veja a Visão geral dos Serviços de notificação por push (WNS) para saber mais sobre conceitos, requisitos e operações de notificação por push e de WNS.

Solicitando e recebendo um token de acesso

Esta seção descreve os parâmetros de solicitação e resposta envolvidos quando você autentica com WNS.

Solicitação de token de acesso

Uma solicitação HTTP é enviada para WNS para autenticar o serviço de nuvem e recuperar um token de acesso em retorno. A solicitação é emitida para o seguinte Fully Qualified Domain Name (FQDN) usando Secure Sockets Layer (SSL).

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

Parâmetros de solicitação de token de acesso

O serviço de nuvem envia estes parâmetros necessários para o corpo solicitante de HTTP, usando o formato "application/x-www-form-urlencoded". Você deve assegurar que todos os parâmetros estejam codificados para URL.

Parâmetro	Necessário/Opcional	Descrição
grant_type	Necessário	Deve ser definido como "client_credentials".
client_id	Necessário	O Identificador de Segurança (SID) do pacote para o seu serviço de nuvem conforme atribuído quando você registrou o seu aplicativo com a Windows Store.
client_secret	Necessário	Chave secreta para o seu serviço de nuvem conforme atribuído quando você registrou o seu aplicativo com a Windows Store
scope	Necessário	Deve ser definido como: Windows: "notify.windows.com" Windows Phone: "notify.windows.com" ou "s.notify.live.net"

Resposta com token de acesso

O WNS autentica o serviço de nuvem e, se bem sucedido, responde com um "200 OK", incluindo o token de acesso. Caso contrário, WNS responde com um código de erro HTTP como descrito no rascunho de protocolo OAuth 2.0.

Parâmetros de resposta com token de acesso

Um token de acesso é retornado na resposta do HTTP se o serviço de nuvem for autenticado com êxito. Este token de acesso pode ser usado em solicitações de notificações até expirar. A resposta do HTTP usa o tipo de mídia "application/json".

Parâmetro	Necessário/Opcional	Descrição
access_token	Necessário	O token de acesso que o serviço de nuvem usará quando ele enviar uma notificação.
token_type	Opcional	Sempre retornado como "bearer".

Código de resposta

Código de resposta de HTTP	Descrição
200 OK	A solicitação foi bem sucedida.
400 Má solicitação	A autenticação falhou. Veja a RFC (Request for Comments) do rascunho de OAuth para os parâmetros de resposta.

Exemplo

O exemplo a seguir mostra uma resposta de autenticação bem-sucedida:

 HTTP/1.1 200 OK   
 Cache-Control: no-store
 Content-Length: 422
 Content-Type: application/json
 
 {
     "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
     "token_type":"bearer"
 }

Enviando uma solicitação de notificação e recebendo uma resposta

Esta seção descreve os cabeçalhos envolvidos em uma solicitação de HTTP para o WNS entregar uma notificação e os envolvidos na resposta.

Enviar solicitação de notificação
Enviar resposta de notificação
Recursos de HTTP não suportados

Enviar solicitação de notificação

Ao enviar uma solicitação de notificação, o aplicativo de chamada faz uma solicitação de HTTP sobre SSL, endereçada para o canal URI. "Content-Length" é um cabeçalho padrão HTTP que deve ser especificado na solicitação. Todos os outros cabeçalhos padrão são opcionais ou não têm suporte.

Além disso, os cabeçalhos de solicitação personalizada listados aqui podem ser usados na solicitação de notificação. Alguns cabeçalhos são necessários enquanto outros são opcionais.

Parâmetros solicitados

Nome do cabeçalho	Necessário/Opcional	Descrição
Authorization	Necessário	O cabeçalho de autorização HTTP padrão usado para autenticar a sua solicitação de notificação. O seu serviço de nuvem fornece o seu token de acesso ao seu cabeçalho.
Content-Type	Necessário	Cabeçalho de autorização HTTP padrão. Para notificações do sistema, de selo e de bloco, esse cabeçalho deve ser definido como "text/xml". Para notificações brutas, esse cabeçalho deve ser definido como "application/octet-stream".
Content-Length	Necessário	Cabeçalho de autorização HTTP padrão para denotar o tamanho da carga solicitante.
X-WNS-Type	Necessário	Define o tipo de notificação na carga: bloco, sistema, emblema ou bruta.
X-WNS-Cache-Policy	Opcional	Habilita ou desabilita o cache de notificação. Este cabeçalho se aplica somente às notificações de bloco, de selo e brutas.
X-WNS-RequestForStatus	Opcional	Solicita o status do dispositivo e o status da conexão WNS na resposta de notificação.
X-WNS-Tag	Opcional	Cadeia de caracteres usada para fornecer uma notificação com um rótulo identificador, usado para bloco que suporta a fila de notificação. Este cabeçalho se aplica somente às notificações de bloco.
X-WNS-TTL	Opcional	Valor inteiro, expresso em segundos, que especifica a vida útil (TTL).
X-WNS-SuppressPopup	Opcional	Somente Windows Phone: oferece uma notificação do sistema diretamente para a central de ações sem acionar o sistema propriamente dito.
X-WNS-Group	Opcional	Windows Phone somente: usado com o cabeçalho X-WNS-Tag para notificações de grupo na central de ações.
X-WNS-Match	Circunstancialmente necessário	Windows Phone somente : necessário para identificar o destino ou destinos quando você remove uma notificação do sistema da central de ações por meio do método HTTP DELETE.

Observações importantes

Content-Length e Content-Type são os únicos cabeçalhos padrão HTTP que estão incluídos na notificação entregue ao cliente, independente se outros cabeçalhos padrão foram incluídos na solicitação.
Todos os outros cabeçalhos padrão HTTP são ignorados ou retornam um erro se a funcionalidade não é suportada.

Authorization

O cabeçalho de autorização é usado para especificar as credenciais da parte chamadora, seguindo o método de autorização OAuth 2.0 para os tokens bearer.

A sintaxe consiste de uma cadeia de caracteres literal "Bearer", seguida de um espaço, seguida de seu token de acesso. Este token de acesso é recuperado emitindo a solicitação de token de acesso descrita acima. O mesmo token de acesso pode ser usado em solicitações de notificação subsequentes até ele expirar.

Esse cabeçalho é necessário.

Authorization: Bearer <access-token>

X-WNS-Type

Estes são os tipos de notificação suportados pelo WNS. Este cabeçalho indica o tipo de notificação e como o WNS deve lidar com ela. Após a notificação alcançar o cliente, a carga real é validada contra este tipo especificado. Esse cabeçalho é necessário.

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

Valor	Descrição
wns/badge	Uma notificação para criar uma sobreposição de selo no bloco. O cabeçalho Content-Type incluído na solicitação de notificação deve ser definido como "text/xml".
wns/tile	Uma notificação para atualizar o conteúdo de bloco. O cabeçalho Content-Type incluído na solicitação de notificação deve ser definido como "text/xml".
wns/toast	Uma notificação para criar uma notificação sobre o cliente. O cabeçalho Content-Type incluído na solicitação de notificação deve ser definido como "text/xml".
wns/raw	Uma notificação que pode conter uma carga personalizada e é entregue diretamente no aplicativo. O cabeçalho Content-Type incluído na solicitação de notificação deve ser definido como "application/octet-stream".

X-WNS-Cache-Policy

Quando o dispositivo de destino de notificação estiver offline, WNS colocará na cache uma notificação de bloco e uma notificação de selo por aplicativo. Se o ciclo de notificação estiver habilitado para o aplicativo, WNS colocará na cache até cinco notificações de bloco. Por padrão, notificações brutas não são armazenadas em cache, mas se o cache de notificações brutas for habilitado, uma notificação bruta será armazenada em cache. Os itens não são mantidos em cache indefinidamente e serão excluídos após um período razoável de tempo. Caso contrário, o conteúdo em cache é entregue quando o dispositivo fica online pela próxima vez.

Esse cabeçalho é opcional e só deve ser usado em casos onde o serviço de nuvem desejar substituir o comportamento de cache padrão.

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

Valor	Descrição
cache	Padrão. As notificações serão armazenadas em cache se o usuário estiver offline. Essa é a configuração padrão para notificações de bloco e de selo.
no-cache	A notificação não será colocada em cache se o usuário estiver offline. Essa é a configuração padrão para notificações brutas.

X-WNS-RequestForStatus

Especifica se a resposta deve incluir o status do dispositivo e o status de conexão WNS. Esse cabeçalho é opcional.

X-WNS-RequestForStatus: true | false

Valor	Descrição
verdadeiro	Retorna o status do dispositivo e o status da notificação na resposta.
falso	Padrão. Não retorna o status do dispositivo e o status da notificação.

X-WNS-Tag

Atribui uma etiqueta tag a uma notificação. A marca é usada na política de substituição do bloco na fila de notificação quando o aplicativo optou pelo ciclo de notificação. Se uma notificação com esta marca já existe na fila, uma nova notificação com a mesma marca pega o seu lugar.

Observação Esse cabeçalho é opcional e é usado somente ao enviar notificações de bloco.

Observação Para os aplicativos da Loja do Windows Phone, o cabeçalho X-WNS-Tag pode ser usado com o cabeçalho X-WNS-Group para permitir que várias notificações com a mesma marca sejam mostradas na central de ações.

X-WNS-Tag: <string value>

Valor	Descrição
valor de cadeia de caracteres	Uma cadeia de caracteres alfanumérica com não mais que 16 caracteres.

X-WNS-TTL

Especifica o TTL (Tempo de expiração) de uma notificação. Ele não é tipicamente necessário, mas pode ser usado se você quiser assegurar que as suas notificações não sejam exibidas depois de uma certa hora. O TTL é especificado em segundos e é relativo ao tempo que o WNS recebe a solicitação. Quando um TTL é especificado, o dispositivo não exibirá a notificação após determinada hora. Note que isso pode resultar na notificação nunca ser mostrada se TTL for pequeno demais. Em geral, um tempo de expiração será medido em, pelo menos, minutos.

Esse cabeçalho é opcional. Se nenhum valor for especificado, a notificação não expirará e será substituída sob o esquema de substituição de notificação normal.

X-WNS-TTL: <integer value>

Valor	Descrição
valor inteiro	O intervalo da notificação, em segundos, após WNS receber a solicitação.

X-WNS-SuppressPopup

Observação Para os aplicativos da Loja do Windows Phone, você tem a opção de suprimir a interface do usuário de uma notificação do sistema, em vez de enviar a notificação diretamente para a central de ações. Isso permite que sua notificação seja entregue silenciosamente, uma opção potencialmente superior para as notificações menos urgentes. Esse cabeçalho é opcional e só é usado nos canais do Windows Phone. Se você incluir esse cabeçalho em um canal do Windows, sua notificação será descartada e você receberá uma resposta de erro do WNS.

X-WNS-SuppressPopup: true | false

Valor	Descrição
verdadeiro	Envia uma notificação do sistema diretamente para a central de ações; não acione a interface do usuário do sistema.
falso	Padrão. Aciona a interface do usuário do sistema, bem como adiciona a notificação à central de ações.

X-WNS-Group

Observação A central de ações de aplicativos da Loja do Windows Phone poderá exibir várias notificações do sistema com a mesma marca somente se elas estiverem identificadas como pertencentes a grupos diferentes. Por exemplo, considere um aplicativo de livro de receitas. Cada receita seria identificada por uma marca. Um sistema que contém um comentário sobre essa receita teria a marca da receita, mas uma marca do grupo de comentário. Um sistema que contém uma classificação para essa receita teria novamente a marca da receita, mas teria uma marca do grupo de classificação. Essas marcas de grupos diferentes permitiriam que ambas as notificações do sistema fossem mostradas imediatamente na central de ações. Esse cabeçalho é opcional.

X-WNS-Group: <string value>

Valor	Descrição
valor de cadeia de caracteres	Uma cadeia de caracteres alfanumérica com não mais que 16 caracteres.

X-WNS-Match

Observação Usado com o método HTTP DELETE para remover uma notificação do sistema específica, um conjunto de notificações (por marca ou grupo) ou todas as notificações da central de ações de aplicativos da Loja do Windows Phone. Esse cabeçalho pode especificar um grupo, uma marca ou ambos. Esse cabeçalho é necessário em uma solicitação de notificação HTTP DELETE. Qualquer conteúdo incluído com essa solicitação de notificação é ignorado.

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

Valor	Descrição
type:wns/toast;group=<string value>;tag=<string value>	Remove uma única notificação identificada tanto com a marca como com o grupo especificado.
type:wns/toast;group=<string value>	Remove todas as notificações identificadas com o grupo especificado.
type:wns/toast;tag=<string value>	Remove todas as notificações identificadas com a marca especificada.
type:wns/toast;all	Limpa todas as notificações do aplicativo da central de ações.

Enviar resposta de notificação

Após o WNS processar a solicitação de notificação, ele envia uma mensagem HTTP em resposta. Esta seção discute os parâmetros e cabeçalhos que podem ser encontrados nessa resposta.

Parâmetros de resposta

Header name	Necessário/Opcional	Descrição
X-WNS-Debug-Trace	Opcional	Informações de depuração que devem ser registradas para ajudar a solucionar problemas ao relatar um problema.
X-WNS-DeviceConnectionStatus	Opcional	O status do dispositivo, retornado somente se solicitado na solicitação de notificação através do cabeçalho X-WNS-RequestForStatus.
X-WNS-Error-Description	Opcional	Uma cadeia de caracteres de erro legível por humanos que deve ser registrada para ajudar na depuração.
X-WNS-Msg-ID	Opcional	Um identificador exclusivo para a notificação, usado para propósitos de depuração. Ao relatar um problema, esta informação deve ser registrada para ajudar na solução de problemas.
X-WNS-Status	Opcional	Indica se o WNS recebeu e processou a notificação com êxito. Ao relatar um problema, estas informações devem ser registradas para ajudar na solução de problemas.

X-WNS-Debug-Trace

Este cabeçalho retorna informações de depuração úteis como uma cadeia de caracteres. Recomendamos que este cabeçalho seja registrado para ajudar aos desenvolvedores a depurar questões. Este cabeçalho e o cabeçalho X-WNS-Msg-ID são necessários para relatar uma questão para WNS.

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

Valor	Descrição
valor de cadeia de caracteres	Uma cadeia de caracteres alfanumérica.

X-WNS-DeviceConnectionStatus

Este cabeçalho retorna o status do dispositivo para o aplicativo chamador, se solicitado no cabeçalho X-WNS-RequestForStatus da solicitação da notificação.

X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected

Valor	Descrição
connected	O dispositivo está online e está conectado a WNS.
disconnected	O dispositivo está offline e não está conectado a WNS.
tempconnected	O dispositivo perdeu temporariamente a conexão para WNS, por exemplo se a conexão 3G caiu ou se a Internet sem fio em um laptop é desligada. Isso é visto pela Plataforma de Cliente de Notificações como uma interrupção temporária em vez de uma desconexão intencional.

X-WNS-Error-Description

Este cabeçalho fornece uma cadeia de caracteres de erro legível por humanos que deve ser registrada para ajudar na depuração.

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

Valor	Descrição
valor da cadeia de caracteres	Uma cadeia de caracteres alfanumérica.

X-WNS-Msg-ID

Este cabeçalho é usado para fornecer ao chamador um identificador para a notificação. Recomendamos que este cabeçalho seja registrado para ajudar a depurar os problemas. Este cabeçalho, junto com o cabeçalho X-WNS-Debug-Trace, é necessário ao relatar um problema para WNS.

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

Valor	Descrição
valor de cadeia de caracteres	Uma cadeia de caracteres alfanumérica com não mais de 16 caracteres.

X-WNS-Status

Este cabeçalho descreve como o WNS lidou com esta solicitação de notificação. Isso pode ser usado em vez de interpretar os códigos de resposta como sucesso ou falha.

X-WNS-Status: received | dropped | channelthrottled

Valor	Descrição
received	A notificação foi recebida e processada por WNS. Observação Isso não garante que o dispositivo recebeu a notificação.
dropped	A notificação foi explicitamente abandonada por causa de um erro ou por causa que o cliente explicitamente rejeitou estas notificações. As notificações do sistema também cairão se o dispositivo ficar offline.
channelthrottled	A notificação foi ignorada porque o servidor do aplicativo excedeu o limite de taxa para este canal específico.

Códigos de resposta

Cada mensagem HTTP contém um desses códigos de resposta. WNS recomenda que os desenvolvedores registrem o código de resposta para uso em depuração. Quando os desenvolvedores relatam uma questão para WNS, eles devem fornecer códigos de resposta e informações de cabeçalho.

Código de resposta HTTP	Descrição	Recommended action
200 OK	A notificação foi aceita por WNS.	Nenhum necessário.
400 Má solicitação	Um ou mais cabeçalhos foram especificados incorretamente ou estão em conflito com outro cabeçalho.	Registre os detalhes de sua solicitação. Inspecione a sua solicitação e compare-a com esta documentação.
401 Não autorizado	O serviço de nuvem não apresentou um tíquete de autenticação válido. O tíquete de OAuth pode ser inválido.	Solicite um token de acesso válido autenticando o seu serviço de nuvem usando a solicitação de token de acesso.
403 Proibido	O serviço de nuvem não está autorizado para enviar uma notificação para este URI apesar de estarem autenticados.	O token de acesso fornecido nesta solicitação não corresponde às credenciais do aplicativo que solicitou o URI de canal. Assegure que o seu nome de pacote em seu manifesto de aplicativo corresponda às credenciais do serviço de nuvem dadas ao seu aplicativo no Painel.
404 Não encontrado	O URI de canal não é válido ou não é reconhecido por WNS.	Registre os detalhes de sua solicitação. Não envie mais notificações para o canal; as notificações para este endereço serão ignoradas.
405 Método não permitido	Método inválido (GET, CREATE); somente POST (Windows ou Windows Phone) ou DELETE (somente Windows Phone) é permitido.	Registre os detalhes de sua solicitação. Alterne para o uso de HTTP POST.
406 Não aceitável	O serviço de nuvem estendeu o seu limite de aceleração.	Registre os detalhes de sua solicitação. Reduza o índice com o qual você está enviando notificações.
410 Expirado	O canal expirou.	Registre os detalhes de sua solicitação. Não envie mais notificações para este canal. Faça com que o seu aplicativo solicite um novo canal URI.
413 Entidade de solicitação grande demais	A carga de notificação excede o limite de tamanho de 5000 bytes.	Registre os detalhes de sua solicitação. Inspecione a carga para assegurar que ela está dentro das limitações de tamanho.
500 Erro interno de servidor	Uma falha interna fez com que a entrega da notificação falhasse.	Registre os detalhes de sua solicitação. Relate esta questão através dos fóruns do desenvolvedor.
503 Servidor indisponível	O servidor está indisponível atualmente.	Registre os detalhes de sua solicitação. Relate esta questão através dos fóruns do desenvolvedor.

Para obter informações detalhadas sobre solução de problemas de códigos de resposta específicos, consulte Solução de problemas de bloco, notificação do sistema e selo. Consulte também COM Error Codes (WPN, MBN, P2P, Bluetooth).

Recursos de HTTP não suportados

A interface de Web WNS aceita HTTP 1.1 mas não aceita os seguintes recursos:

Criação de partes
Pipelining (POST não é idempotente)
Apesar de aceito, os desenvolvedores devem desabilitar o Expect-100, já que ele introduz latência ao enviar uma notificação.

Tópicos relacionados

Guia de início rápido: enviando uma notificação por push

Diretrizes e lista de verificação de botões de alternância

Como autenticar com o Serviço de Notificação por Push do Windows (WNS)

Como solicitar, criar e salvar um canal de notificação

Exemplo de notificações por push e periódicas

Visão geral do WNS

Compartilhar via