Cabeçalhos de solicitação e resposta de serviço de notificação por push
Idioma: HTML | XAML

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.

ParâmetroNecessário/OpcionalDescrição
grant_typeNecessárioDeve ser definido como "client_credentials".
client_idNecessárioO 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_secretNecessárioChave secreta para o seu serviço de nuvem conforme atribuído quando você registrou o seu aplicativo com a Windows Store
scopeNecessárioDeve 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âmetroNecessário/OpcionalDescrição
access_tokenNecessárioO token de acesso que o serviço de nuvem usará quando ele enviar uma notificação.
token_typeOpcionalSempre retornado como "bearer".

 

Código de resposta

Código de resposta de HTTPDescrição
200 OKA solicitação foi bem sucedida.
400 Má solicitaçãoA 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

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çalhoNecessário/OpcionalDescrição
AuthorizationNecessárioO 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-TypeNecessárioCabeç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-LengthNecessárioCabeçalho de autorização HTTP padrão para denotar o tamanho da carga solicitante.
X-WNS-TypeNecessárioDefine o tipo de notificação na carga: bloco, sistema, emblema ou bruta.
X-WNS-Cache-PolicyOpcionalHabilita ou desabilita o cache de notificação. Este cabeçalho se aplica somente às notificações de bloco, de selo e brutas.
X-WNS-RequestForStatusOpcionalSolicita o status do dispositivo e o status da conexão WNS na resposta de notificação.
X-WNS-TagOpcionalCadeia 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-TTLOpcionalValor inteiro, expresso em segundos, que especifica a vida útil (TTL).
X-WNS-SuppressPopupOpcionalSomente Windows Phone: oferece uma notificação do sistema diretamente para a central de ações sem acionar o sistema propriamente dito.
X-WNS-GroupOpcionalWindows Phone somente: usado com o cabeçalho X-WNS-Tag para notificações de grupo na central de ações.
X-WNS-MatchCircunstancialmente necessárioWindows 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
ValorDescrição
wns/badgeUma 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/tileUma 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/toastUma 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/rawUma 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
ValorDescrição
cachePadrã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-cacheA 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
ValorDescrição
verdadeiroRetorna o status do dispositivo e o status da notificação na resposta.
falsoPadrã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>
ValorDescrição
valor de cadeia de caracteresUma 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>
ValorDescrição
valor inteiroO 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
ValorDescrição
verdadeiroEnvia uma notificação do sistema diretamente para a central de ações; não acione a interface do usuário do sistema.
falsoPadrã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>
ValorDescrição
valor de cadeia de caracteresUma 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
ValorDescriçã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;allLimpa 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 nameNecessário/OpcionalDescrição
X-WNS-Debug-TraceOpcionalInformações de depuração que devem ser registradas para ajudar a solucionar problemas ao relatar um problema.
X-WNS-DeviceConnectionStatusOpcionalO status do dispositivo, retornado somente se solicitado na solicitação de notificação através do cabeçalho X-WNS-RequestForStatus.
X-WNS-Error-DescriptionOpcionalUma cadeia de caracteres de erro legível por humanos que deve ser registrada para ajudar na depuração.
X-WNS-Msg-IDOpcionalUm 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-StatusOpcionalIndica 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>
ValorDescrição
valor de cadeia de caracteresUma 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
ValorDescrição
connectedO dispositivo está online e está conectado a WNS.
disconnectedO dispositivo está offline e não está conectado a WNS.
tempconnectedO 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 caracteresUma 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>
ValorDescrição
valor de cadeia de caracteresUma 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
ValorDescrição
receivedA notificação foi recebida e processada por WNS.
Observação  Isso não garante que o dispositivo recebeu a notificação.
 
droppedA 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.
channelthrottledA 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 HTTPDescriçãoRecommended action
200 OKA notificação foi aceita por WNS.Nenhum necessário.
400 Má solicitaçãoUm 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 autorizadoO 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 ProibidoO 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 encontradoO 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 permitidoMé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ávelO 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 ExpiradoO 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 demaisA 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 servidorUma 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

 

 

Mostrar:
© 2016 Microsoft