Partilhar via

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

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

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

Solicitar e receber um token de acesso

Esta seção descreve os parâmetros de solicitação e resposta envolvidos quando você se autentica 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 para https://login.live.com/accesstoken.srf usando Secure Sockets Layer (SSL).

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

O serviço de nuvem envia esses parâmetros necessá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.

Parameter Required Description
grant_type TRUE Deve ser definido como client_credentials.
client_id TRUE Identificador de segurança de pacote (SID) para seu serviço de nuvem, conforme atribuído quando você registrou seu aplicativo na Microsoft Store.
client_secret TRUE Chave secreta para o seu serviço na nuvem, conforme atribuído quando registou a sua aplicação na Microsoft Store.
âmbito TRUE Deve ser definido como notify.windows.com

Resposta do token de acesso

O WNS autentica o serviço de nuvem e, se for bem-sucedido, responde com um "200 OK", incluindo o token de acesso. Caso contrário, o WNS responde com um código de erro HTTP apropriado, 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 êxito. 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".

Parameter Required Description
access_token TRUE O token de acesso que o serviço de nuvem usará quando enviar uma notificação.
token_type FALSE Sempre retornava como bearer.

Código de resposta

Código de resposta HTTP Description
200 OK O pedido foi bem-sucedido.
400 Pedido Inválido A autenticação falhou. Consulte o rascunho do OAuth Request for Comments (RFC) para obter os parâmetros de resposta.

Example

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 um pedido 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 pedido de notificação
  • Enviar resposta de notificação
  • Recursos HTTP não suportados

Enviar pedido de notificação

Ao enviar uma solicitação de notificação, o aplicativo de chamada faz uma solicitação HTTP sobre 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 não são suportados.

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 de solicitação

Nome do cabeçalho Required Description
Authorization TRUE Cabeçalho de autorização HTTP padrão usado para autenticar sua solicitação de notificação. Seu serviço de nuvem fornece seu token de acesso neste cabeçalho.
Content-Type TRUE Cabeçalho de autorização HTTP padrão. Para notificações de brindes, bloco e emblema, este 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 da carga útil da solicitação.
X-WNS-Type TRUE Define o tipo de notificação na carga útil: bloco, toast, selo ou raw.
X-WNS-Cache-Policy FALSE Habilita ou desabilita o cache de notificações. Este cabeçalho aplica-se apenas a notificações de mosaico, selo e não processadas.
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 String usada para fornecer uma notificação com um rótulo identificador, usada para tiles que suportam a fila de notificações. Este cabeçalho aplica-se apenas a notificações de mosaico.
X-WNS-TTL FALSE Valor inteiro, expresso em segundos, que especifica o tempo de vida (TTL).
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 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 suportada.
  • A partir de fevereiro de 2023, o WNS irá armazenar em cache apenas uma notificação de tile quando o dispositivo estiver offline.

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 tokens bearer.

A sintaxe consiste em uma cadeia de caracteres literal "Portador", seguida por um espaço, seguido pelo seu token de acesso. Esse 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é expirar.

Este cabeçalho é obrigatório.

Authorization: Bearer <access-token>

X-WNS-Type

Estes são os tipos de notificação suportados pelo 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, a carga real é validada em relação a esse tipo especificado. Este cabeçalho é obrigatório.

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw
Value Description
wns/badge Uma notificação para criar uma sobreposição de símbolo no azulejo. 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 do azulejo. 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 fazer um brinde no 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, o WNS armazenará em cache um selo, um bloco e uma notificação toast para a URI de cada 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 indefinidamente e serão descartados após um período de tempo razoável. Caso contrário, o conteúdo armazenado em cache será entregue na próxima vez que o dispositivo ficar online.

X-WNS-Cache-Policy: cache | no-cache
Value Description
cache Default. As notificações serão armazenadas em cache se o usuário estiver offline. Esta é a configuração padrão para notificações de mosaico e emblema.
no-cache A notificação não será armazenada em cache se o usuário estiver offline. Esta é 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. Este cabeçalho é opcional.

    X-WNS-RequestForStatus: true | false
Value Description
true Retorne o status do dispositivo e o status da notificação na resposta.
false Default. Não restitua o estado do dispositivo nem o da notificação.

X-WNS-Tag

Atribui um rótulo a uma notificação. A tag é utilizada na política de substituição do painel na fila de notificações quando a aplicação optou pela ciclagem de notificações. Se já existir uma notificação com essa tag na fila, uma nova notificação com a mesma tag será substituída.

Note

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

    X-WNS-Tag: <string value>
Value Description
Valor da string Uma cadeia alfanumérica de no máximo 16 caracteres.

X-WNS-TTL

Especifica o TTL (tempo de expiração) para uma notificação. Isso normalmente não é necessário, mas pode ser usado se você quiser garantir que suas notificações não sejam exibidas depois de um determinado tempo. 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 esse tempo. 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.

Este cabeçalho é opcional. Se não for especificado qualquer valor, a notificação não caduca e será substituída ao abrigo do regime normal de substituição da notificação.

X-WNS-TTL: <integer value>

Value Description
valor inteiro O tempo de vida da notificação, em segundos, após o WNS receber a solicitação.

X-WNS-SuppressPopup

Note

Para 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 notificações menos urgentes. Este 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: verdadeiro | falso

Value Description
true Envie a notificação toast diretamente para a central de ações; não mostre a interface do usuário toast.
false Default. Aumente a interface do usuário do sistema e adicione a notificação à central de ações.

X-WNS-Group

Note

O centro de ação para aplicações da Loja do Windows Phone pode exibir várias notificações de 'toast' com a mesma etiqueta apenas se estiverem identificadas como pertencendo a grupos diferentes. Por exemplo, considere um aplicativo de livro de receitas. Cada receita seria identificada por uma etiqueta. Um toast que contenha um comentário sobre essa receita teria a etiqueta da receita, mas um rótulo de grupo de comentário. Um brinde que contenha uma classificação para essa receita teria novamente a etiqueta dessa receita, mas teria um rótulo de grupo de classificação. Esses diferentes rótulos de grupo permitiriam que ambas as notificações toast fossem mostradas simultaneamente na central de ações. Este cabeçalho é opcional.

Grupo X-WNS: <string value>

Value Description
Valor da string Uma cadeia alfanumérica de no máximo 16 caracteres.

X-WNS-Match

Note

Usado com o método HTTP DELETE para remover um toast específico, um conjunto de toasts (por tag ou grupo) ou todos os toasts do centro de notificações para aplicativos da Loja do Windows Phone. Esse cabeçalho pode especificar um grupo, uma tag ou ambos. Esse cabeçalho é necessário em uma solicitação de notificação HTTP DELETE. Qualquer carga incluída nesta solicitação de notificação é ignorada.

X-WNS-Match: tipo:wns/toast;grupo=<string value>;tag=<string value>|tipo:wns/toast;grupo=<string value>|tipo:wns/toast;tag=<string value>|tipo:wns/toast;all

Value Description
tipo: wns/toast; grupo=<string value>; etiqueta=<string value> Remova uma única notificação rotulada com a tag e o grupo especificados.
Tipo:WNS/Toast; grupo=<string value> Remova todas as notificações rotuladas com o grupo especificado.
Tipo:WNS/Toast; tag=<string value> Remova todas as notificações rotuladas com a tag especificada.
type:wns/toast;all Limpe todas as notificações do seu 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 cabeçalhos que podem ser encontrados nessa resposta.

Parâmetros de resposta

Nome do cabeçalho Required Description
X-WNS-Debug-Trace FALSE Informações de depuração que devem ser registadas para ajudar a solucionar problemas ao reportar um problema.
X-WNS-DeviceConnectionStatus FALSE O estado do dispositivo, retornado apenas se solicitado através do cabeçalho X-WNS-RequestForStatus no pedido de notificação.
X-WNS-Error-Description FALSE Uma cadeia de erro legível 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 êxito. 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 registadas para ajudar a solucionar problemas ao reportar um problema.

X-WNS-Debug-Trace

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

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

Value Description
Valor da cadeia de caracteres Uma cadeia 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: conectado | desconectado | tempdisconnected

Value Description
connected O dispositivo está online e conectado ao WNS.
disconnected O dispositivo está offline e não está conectado ao WNS.
TempConnected (descontinuado) O dispositivo perdeu temporariamente a conexão com o WNS, por exemplo, quando uma conexão 3G é interrompida ou o interruptor sem fio em um laptop é lançado. É 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

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

X-WNS-Erro-Descrição: <string value>

Value Description
Valor de string Uma cadeia 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 para ajudar a depurar problemas. Esse cabeçalho, juntamente com o X-WNS-Debug-Trace e o MS-CV, são necessários ao relatar um problema ao WNS.

ID X-WNS-MSG: <string value>

Value Description
Valor de string Uma cadeia alfanumérica de no máximo 16 caracteres.

X-WNS-Status

Este 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 sucesso ou falha.

X-WNS-Status: recebido | descartado | canal limitado

Value Description
received A notificação foi recebida e processada pela WNS. Nota: Isto 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 rejeitou explicitamente essas notificações. As notificações toast também serão descartadas se o dispositivo estiver offline.
channelthrottled A notificação foi descartada porque o servidor do aplicativo excedeu o limite de taxa para esse canal específico.

MS-CV

Este 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á com um CV. Esse cabeçalho, juntamente com o cabeçalho X-WNS-Debug-Trace e X-WNS-Msg-ID, são necessários ao relatar um problema ao WNS.

Important

Por favor, gere um novo CV para cada pedido de notificação push, se estiver a fornecer o seu próprio CV.

MS-CV: <string value>

Value Description
Valor de string Segue o padrão Vetor de Correlação

Código 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 Description Ação recomendada
200 OK A notificação foi aceite pela WNS. Não é necessário.
400 Pedido Inválido Um ou mais cabeçalhos foram especificados incorretamente ou entram em conflito com outro cabeçalho. Registe os detalhes do seu pedido. Inspecione o seu pedido e compare 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 bilhete OAuth pode ser inválido. Solicite um token de acesso válido autenticando seu serviço de nuvem usando a 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 eles estejam autenticados. O token de acesso fornecido na solicitação não corresponde às credenciais do aplicativo que solicitou o URI do canal. Certifique-se de que 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. Registe os detalhes do seu pedido. Não envie mais notificações para este canal; As notificações para este endereço falharão.
Método 405 Não permitido Método inválido (GET, CREATE); apenas POST (Windows ou Windows Phone) ou DELETE (somente Windows Phone) são permitidos. Registe os detalhes do seu pedido. Mude para usar HTTP POST.
406 Não aceitável O serviço de nuvem excedeu o seu limite de utilização. Por favor, envie o seu pedido após o valor do cabeçalho Retry-After na resposta
410 Desaparecido O canal expirou. Registe os detalhes do seu pedido. Não envie mais notificações para este 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 este canal. O domínio de envio foi bloqueado pelo WNS por abusar das notificações push.
413 Entidade de solicitação muito grande A carga útil de notificação excede o limite de tamanho de 5000 bytes. Registe os detalhes do seu pedido. Inspecione a carga útil para garantir que está dentro das limitações de tamanho.
500 Erro interno do servidor Uma falha interna fez com que a entrega de notificações falhasse. Registe os detalhes do seu pedido. Denuncie este problema através dos fóruns de programadores.
503 Serviço indisponível O servidor está indisponível no momento. Registe os detalhes do seu pedido. Denuncie este problema através dos fóruns de programadores. 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 não suportados

A interface Web WNS suporta HTTP 1.1, mas não suporta os seguintes recursos:

  • Chunking
  • Pipelining (o POST não é idempotente)
  • Embora suportado, os desenvolvedores devem desativar o Expect-100, pois isso introduz latência ao enviar uma notificação.
  • Last updated on