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

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

Confira a visão geral dos Serviços de Notificação por Push do Windows (WNS) para ver uma discussão teórica sobre os conceitos, os requisitos e a operação das notificações por push e do WNS.

Solicitando e recebendo um token de acesso

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

Solicitação de token de acesso

Uma solicitação HTTP é enviada ao WNS para autenticar o serviço de nuvem e recuperar um token de acesso em troca. A solicitação é emitida ao https://login.live.com/accesstoken.srf usando o protocolo SSL.

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

O serviço de nuvem envia esses parâmetros obrigatórios no corpo da solicitação HTTP, usando o formato "application/x-www-form-urlencoded". Você deve garantir que todos os parâmetros sejam codificados por URL.

Parâmetro	Obrigatório	Descrição
grant_type	TRUE	Deve ser definido como client_credentials.
client_id	TRUE	O SID (identificador de segurança) do pacote do seu serviço de nuvem, atribuído quando você registrou seu aplicativo na Microsoft Store.
client_secret	TRUE	A chave secreta do seu serviço de nuvem, atribuída quando você registrou seu aplicativo na Microsoft Store.
scope	TRUE	Precisa ser definida como notify.windows.com

Resposta de 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, o WNS responderá com um código de erro HTTP adequado, conforme descrito no rascunho do protocolo OAuth 2.0.

Parâmetros de resposta do token de acesso

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

Parâmetro	Obrigatório	Descrição
access_token	TRUE	O token de acesso que o serviço de nuvem usará ao enviar uma notificação.
token_type	FALSE	Sempre retornado como bearer.

Código de resposta

Código de resposta HTTP	Descrição
200 OK	A solicitação foi bem-sucedida.
400 Solicitação Incorreta	A autenticação falhou. Veja o de Request For Comments (RFC) do rascunho do OAuth para obter parâmetros de resposta.

Exemplo

O exemplo a seguir mostra um exemplo de 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",
     "expires_in": 86400
 }

Enviar uma solicitação de notificação e receber uma resposta

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

• Enviar solicitação de notificação
• Enviar resposta de notificação
• Recursos HTTP incompatíveis

Enviar solicitação de notificação

Ao enviar uma solicitação de notificação, o aplicativo de chamada faz uma solicitação HTTP por SSL, endereçada ao URI (Uniform Resource Identifier) do canal. "Content-Length" é um cabeçalho HTTP padrão que deve ser especificado na solicitação. Todos os outros cabeçalhos padrão são opcionais ou incompatíveis.

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

Parâmetros da solicitação

Nome do cabeçalho	Obrigatório	Descrição
Autorização	TRUE	Cabeçalho de autorização HTTP padrão usado para autenticar sua solicitação de notificação. Seu serviço de nuvem fornece o token de acesso nesse cabeçalho.
Content-Type	TRUE	Cabeçalho de autorização HTTP padrão. Para notificações do sistema, de bloco e de selo, 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	TRUE	Cabeçalho de autorização HTTP padrão para indicar o tamanho do conteúdo da solicitação.
X-WNS-Type	TRUE	Define o tipo de notificação no conteúdo: bloco, do sistema, selo ou bruta.
X-WNS-Cache-Policy	FALSE	Habilita ou desabilita o cache de notificação. Esse cabeçalho se aplica somente a blocos, selos e notificações brutas.
X-WNS-RequestForStatus	FALSE	Solicita o status do dispositivo e o status da conexão WNS na resposta de notificação.
X-WNS-Tag	FALSE	Cadeia de caracteres usada para fornecer uma notificação com um rótulo de identificação, usado para blocos que são compatíveis com a fila de notificações. Esse cabeçalho se aplica apenas a notificações de bloco.
X-WNS-TTL	FALSE	Valor inteiro, expresso em segundos, que especifica a TTL (vida útil)
MS-CV	FALSE	Valor do vetor de correlação usado para sua solicitação.

Observações importantes

• Content-Length e Content-Type são os únicos cabeçalhos HTTP padrão incluídos na notificação que é entregue ao cliente, independentemente de outros cabeçalhos padrão terem sido incluídos na solicitação.
• Todos os outros cabeçalhos HTTP padrão são ignorados ou retornam um erro se a funcionalidade não for compatível.
• A partir de fevereiro de 2023, o WNS armazenará em cache apenas uma notificação de bloco quando o dispositivo estiver offline.

Autorização

O cabeçalho de autorização é usado para especificar as credenciais da parte que está fazendo a chamada, seguindo o método de autorização OAuth 2.0 para tokens de portador.

A sintaxe consiste em um literal de cadeia de caracteres "Portador", seguido por um espaço, seguido pelo token de acesso. Esse token de acesso é recuperado por meio da emissão da solicitação de token de acesso descrita acima. O mesmo token de acesso pode ser usado em solicitações de notificação subsequentes até expirar.

Esse cabeçalho é obrigatório.

Authorization: Bearer <access-token>

X-WNS-Type

Esses são os tipos de notificação compatíveis com o WNS. Esse cabeçalho indica o tipo de notificação e como o WNS deve lidar com ela. Depois que a notificação chega ao cliente, o conteúdo real é validado em relação a esse tipo especificado. Esse cabeçalho é obrigató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 no bloco. O cabeçalho do tipo de conteúdo incluído na solicitação de notificação deve ser definido como text/xml.
wns/tile	Uma notificação para atualizar o conteúdo do bloco. O cabeçalho do tipo de conteúdo incluído na solicitação de notificação deve ser definido como text/xml.
wns/toast	Uma maneira de gerar uma notificação do sistema no cliente. O cabeçalho do tipo de conteúdo incluído na solicitação de notificação deve ser definido como text/xml.
wns/raw	Uma notificação que pode conter um conteúdo personalizado e é entregue diretamente ao 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, o WNS armazenará em cache um selo, um bloco e uma notificação do sistema para cada URI de canal. Por padrão, as notificações brutas não são armazenadas em cache, mas se o cache de notificações brutas estiver habilitado, uma notificação bruta será armazenada em cache. Os itens não são mantidos no cache por tempo indeterminado e serão removidos após um período razoável. Caso contrário, o conteúdo armazenado em cache será entregue na próxima vez que o dispositivo estiver online.

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 selo.
no-cache	A notificação não será armazenada 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 da conexão WNS. Esse cabeçalho é opcional.

    X-WNS-RequestForStatus: true | false

Valor	Descrição
true	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 um marca de rótulo 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ções. Se já existir uma notificação com essa marca na fila, uma nova notificação com a mesma marca tomará seu lugar.

Observação

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

    X-WNS-Tag: <string value>

Valor	Descrição
valor da cadeia de caracteres	Uma cadeia de caracteres alfanumérica de no máximo 16 caracteres.

X-WNS-TTL

Especifica o tempo de expiração (TTL) de uma notificação. Geralmente, isso não é necessário, mas pode ser usado se você quiser garantir que suas notificações não sejam exibidas depois de um determinado momento. O TTL é especificado em segundos e é relativo ao tempo em que o WNS recebe a solicitação. Quando um TTL é especificado, o dispositivo não exibirá a notificação após esse horário. Observe que isso pode fazer com que a notificação nunca seja mostrada se o TTL for muito curto. 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 de acordo com o esquema normal de substituição de notificação.

X-WNS-TTL: <integer value>

Valor	Descrição
valor inteiro	A vida útil da notificação, em segundos, após o WNS receber a solicitação.

X-WNS-SuppressPopup

Observação

Para aplicativos da Windows Phone Store, 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 notificações menos urgentes. Esse cabeçalho é opcional e usado apenas em 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
true	Envia a notificação do sistema diretamente para a central de ações; não aciona a interface do usuário da notificação do sistema.
falso	Padrão. Aciona a interface do usuário da notificação do sistema, bem como adiciona a notificação à central de ações.

X-WNS-Group

Observação

A central de ações para aplicativos da Windows Phone Store só pode exibir várias notificações do sistema com a mesma marca se elas forem rotuladas como pertencentes a grupos diferentes. Por exemplo, considere um aplicativo de livro de receitas. Cada receita seria identificada por uma marca. Um notificação do sistema que contém um comentário sobre essa receita teria a marca da receita, mas um rótulo de grupo de comentários. Uma notificação do sistema que contém uma classificação para essa receita teria novamente a marca dessa receita, mas teria um rótulo de grupo de classificação. Esses rótulos de grupo diferentes permitiriam que ambas as notificações do sistema fossem mostradas de uma só vez na central de ações. Esse cabeçalho é opcional.

X-WNS-Group: <string value>

Valor	Descrição
valor da cadeia de caracteres	Uma cadeia de caracteres alfanumérica de no máximo 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 do sistema (por marca ou grupo) ou todas as notificações do sistema que estão no centro de ações para aplicativos da Windows Phone Store. Esse cabeçalho pode especificar um grupo, uma marca ou ambos. Esse cabeçalho é obrigatório em uma solicitação de notificação HTTP DELETE. Qualquer conteúdo incluído nessa 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 rotulada com a marca e o grupo especificados.
type:wns/toast;group=<string value>	Remove todas as notificações rotuladas com o grupo especificado.
type:wns/toast;tag=<string value>	Remove todas as notificações rotuladas 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

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

Parâmetros de resposta

Nome do cabeçalho	Obrigatório	Descrição
X-WNS-Debug-Trace	FALSE	Informações de depuração que devem ser registradas para ajudar a solucionar problemas ao relatar um problema.
X-WNS-DeviceConnectionStatus	FALSE	O status do dispositivo, retornado somente se for pedido na solicitação de notificação por meio do cabeçalho X-WNS-RequestForStatus.
X-WNS-Error-Description	FALSE	Uma cadeia de caracteres com erros legíveis por humanos que deve ser registrada para ajudar na depuração.
X-WNS-Msg-ID	FALSE	Um identificador exclusivo para a notificação, usado para fins de depuração. Ao relatar um problema, essas informações devem ser registradas para ajudar na solução de problemas.
X-WNS-Status	FALSE	Indica se o WNS recebeu e processou a notificação com sucesso. Ao relatar um problema, essas informações devem ser registradas para ajudar na solução de problemas.
MS-CV	FALSE	Informações de depuração que devem ser registradas para ajudar a solucionar problemas ao relatar um problema.

X-WNS-Debug-Trace

Esse cabeçalho retorna informações úteis sobre a depuração, como uma cadeia de caracteres. Recomendamos que esse cabeçalho seja registrado para ajudar os desenvolvedores a depurar problemas. Esse cabeçalho, juntamente com o cabeçalho X-WNS-Msg-ID e o MS-CV, são obrigatórios para relatar um problema ao WNS.

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

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

X-WNS-DeviceConnectionStatus

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

X-WNS-DeviceConnectionStatus: connected | disconnected | tempdisconnected

Valor	Descrição
connected	O dispositivo está online e conectado ao WNS.
desconectado	O dispositivo está offline e não está conectado ao WNS.
tempconnected (preterido)	O dispositivo perdeu temporariamente a conexão com o WNS, por exemplo, quando uma conexão 3G é interrompida ou a opção sem fio é acionada em um notebook. Ele é visto pela Plataforma de Cliente de Notificação como uma interrupção temporária em vez de uma desconexão intencional.

X-WNS-Error-Description

Esse cabeçalho fornece uma cadeia de caracteres com erros legíveis 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

Esse cabeçalho é usado para fornecer ao chamador um identificador para a notificação. Recomendamos que esse cabeçalho seja registrado em log para ajudar a depurar problemas. Esse cabeçalho, juntamente com o cabeçalho X-WNS-Debug-Trace e MS-CV, são obrigatórios para relatar um problema ao WNS.

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

Valor	Descrição
valor da cadeia de caracteres	Uma cadeia de caracteres alfanumérica de no máximo 16 caracteres.

X-WNS-Status

Esse cabeçalho descreve como o WNS lidou com a solicitação de notificação. Isso pode ser usado em vez de interpretar códigos de resposta como "bem-sucedido" ou "com falha".

X-WNS-Status: received | dropped | channelthrottled

Valor	Descrição
recebidos	A notificação foi recebida e processada pelo WNS. Observação:�isso não garante que o dispositivo recebeu a notificação.
dropped	A notificação foi explicitamente descartada devido a um erro ou porque o cliente explicitamente rejeitou essas notificações. As notificações do sistema também serão descartadas se o dispositivo estiver offline.
channelthrottled	A notificação foi descartada porque o servidor de aplicativos excedeu o limite de taxa desse canal específico.

MS-CV

Esse cabeçalho fornece um Vetor de Correlação relacionado à solicitação que é usado principalmente para depuração. Se um CV for fornecido como parte da solicitação, o WNS usará esse valor; caso contrário, o WNS gerará e responderá de volta com um CV. Esse cabeçalho, juntamente com o cabeçalho X-WNS-Debug-Trace e X-WNS-Msg-ID, são obrigatórios para relatar um problema ao WNS.

Importante

Se você estiver fornecendo seu próprio CV, here um novo CV para cada solicitação de notificação por push.

MS-CV: <string value>

Valor	Descrição
valor da cadeia de caracteres	Segue o padrão do Vetor de Correlação

Códigos de resposta

Cada mensagem HTTP contém um desses códigos de resposta. O WNS recomenda que os desenvolvedores registrem o código de resposta para uso na depuração. Quando os desenvolvedores relatam um problema ao WNS, eles são obrigados a fornecer códigos de resposta e informações de cabeçalho.

Código de resposta HTTP	Descrição	Ação recomendada
200 OK	A notificação foi aceita pelo WNS.	Nenhuma necessária.
400 Solicitação Incorreta	Um ou mais cabeçalhos foram especificados incorretamente ou entraram em conflito com outro cabeçalho.	Registre os detalhes da solicitação. Inspecione sua solicitação e compare com essa 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 OAuth pode ser inválido.	Solicite um token de acesso válido autenticando seu serviço de nuvem por meio da solicitação de token de acesso.
403 Proibido	O serviço de nuvem não está autorizado a enviar uma notificação para esse URI, mesmo que esteja autenticado.	O token de acesso fornecido na solicitação não corresponde às credenciais do aplicativo que solicitou o URI do canal. Verifique se o nome do pacote no manifesto do aplicativo corresponde às credenciais do serviço de nuvem fornecidas ao seu aplicativo no Painel.
404 Não Encontrado	O URI do canal não é válido ou não é reconhecido pelo WNS.	Registre os detalhes da solicitação. Não envie mais notificações para esse canal; as notificações para esse endereço falharão.
405 Método Não Permitido	Método inválido (GET, CREATE); somente os métodos POST (Windows ou Windows Phone) ou DELETE (somente Windows Phone) são permitidos.	Registre os detalhes da solicitação. Mude para usar HTTP POST.
406 Não Aceitável	O serviço de nuvem excedeu seu limite de restrição.	Envie sua solicitação após o valor do cabeçalho Retry-After na resposta
410 não existe mais	O canal expirou.	Registre os detalhes da solicitação. Não envie mais notificações para esse canal. Faça com que seu aplicativo solicite um novo URI de canal.
410 Domínio Bloqueado	O domínio de envio foi bloqueado pelo WNS.	Não envie mais notificações para esse canal. O domínio de envio foi bloqueado pelo WNS por utilização indevida de notificações por push.
Solicitação 413 entidade muito grande	O conteúdo da notificação excede o limite de tamanho de 5.000 bytes.	Registre os detalhes da solicitação. Inspecione o conteúdo para garantir que ele esteja dentro das limitações de tamanho.
Erro interno de servidor 500	Uma falha interna fez com que a entrega de notificação falhasse.	Registre os detalhes da solicitação. Denuncie esse problema por meio dos fóruns do desenvolvedor.
503 Serviço Indisponível	O servidor está atualmente indisponível.	Registre os detalhes da solicitação. Denuncie esse problema por meio dos fóruns do desenvolvedor. Se o cabeçalho Retry-After for observado, envie sua solicitação após o valor do cabeçalho Retry-After na resposta.

Recursos HTTP incompatíveis

A Interface da Web WNS é compatível com o HTTP 1.1, mas não é compatível com os seguintes recursos:

• Agrupamento
• Pipelining (POST não é idempotente)
• Embora seja compatível, os desenvolvedores devem desabilitar o Expect-100, pois ele gera latência ao enviar uma notificação.