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

[ 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.

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".

Código 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

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

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

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

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>

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>

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

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>

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

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

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>

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

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>

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>

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

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.

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