Compartilhar via

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.

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

Solicitando e recebendo um token de acesso

Esta seção descreve os parâmetros de solicitação e resposta envolvidos ao autenticar 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 SSL (Secure Sockets Layer).

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 em URL.

Parâmetro Obrigatório Descrição
tipo_de_concessão VERDADEIRO Deve ser definido como client_credentials.
ID do cliente VERDADEIRO SID (identificador de segurança de pacote) para seu serviço de nuvem conforme atribuído quando você registrou seu aplicativo na Microsoft Store.
segredo_do_cliente VERDADEIRO Chave secreta para seu serviço de nuvem conforme atribuído quando você registrou seu aplicativo na Microsoft Store.
âmbito VERDADEIRO 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 apropriado, conforme descrito no rascunho do protocolo OAuth 2.0.

Parâmetros de resposta do token de acesso

Um token de acesso será 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".

Parâmetro Obrigatório Descrição
token_de_acesso VERDADEIRO O token de acesso que o serviço de nuvem usará quando enviar uma notificação.
tipo_de_token FALSO Sempre retornado como bearer.

Código da resposta

Código de resposta HTTP Descrição
200 OK A solicitação foi bem-sucedida.
400 Solicitação Inválida Falha na autenticação. Consulte o rascunho do OAuth Request for Comments (RFC) para obter parâmetros de resposta.

Exemplo

O seguinte 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 sem suporte

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 não têm suporte.

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 necessários, enquanto outros são opcionais.

Parâmetros de solicitação

Nome do cabeçalho Obrigatório Descrição
Autorização VERDADEIRO 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 nesse cabeçalho.
Tipo de conteúdo VERDADEIRO Cabeçalho de autorização HTTP padrão. Para notificações de toast, tile e selo, esse cabeçalho deve ser definido como text/xml. Para notificações brutas, esse cabeçalho deve ser definido como application/octet-stream.
Tamanho do conteúdo VERDADEIRO Cabeçalho de autorização HTTP padrão para indicar o tamanho do conteúdo da solicitação.
X-WNS-Type VERDADEIRO Define o tipo de notificação na carga útil: bloco, toast, ícone, ou raw.
X-WNS-Cache-Policy FALSO Habilita ou desabilita o cache de notificação. Esse cabeçalho se aplica somente a blocos, ícones e notificações não processadas.
X-WNS-RequestForStatus FALSO Solicita o status do dispositivo e o status da conexão WNS na resposta de notificação.
X-WNS-Tag FALSO Cadeia de caracteres usada para fornecer uma notificação com um rótulo de identificação, usado para blocos que dão suporte à fila de notificação. Esse cabeçalho se aplica apenas a notificações de bloco.
X-WNS-TTL FALSO Valor inteiro, expresso em segundos, que especifica o tempo de vida útil (TTL).
MS-CV FALSO Vetor de Correlação valor usado para sua solicitação.

Notas 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 serão ignorados ou retornarão um erro se a funcionalidade não tiver suporte.
  • A partir de fevereiro de 2023, o WNS armazenará em cache apenas uma notificação de tile quando o dispositivo estiver offline.

Autorização

O cabeçalho de autorização é usado para especificar as credenciais da parte que faz a chamada, seguindo o método de autorização OAuth 2.0 para tokens do tipo bearer .

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

Esse cabeçalho é necessá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, a carga útil real é validada em relação a esse tipo especificado. Esse cabeçalho é necessário.

X-WNS-Type: wns/toast | wns/badge | wns/tile | wns/raw
Valor Descrição
wns/distintivo Uma notificação para criar uma sobreposição de selo no tile. O cabeçalho Content-Type incluído na solicitação de notificação deve ser definido como text/xml.
wns/bloco Uma notificação para atualizar o conteúdo do bloco. O cabeçalho Content-Type incluído na solicitação de notificação deve ser definido como text/xml.
wns/brinde Uma notificação para exibir um aviso 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 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 notificação de destino estiver offline, o WNS armazenará em cache uma insígnia, um bloco e uma notificação toast 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ção bruta estiver habilitado, uma notificação bruta será armazenada em cache. Os itens não são mantidos no cache indefinidamente e serão removidos após um período razoável. Caso contrário, o conteúdo armazenado em cache será entregue quando o dispositivo estiver online em seguida.

X-WNS-Cache-Policy: cache | no-cache
Valor Descrição
armazenamento temporário 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.
sem 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
verdadeiro Retorne o status do dispositivo e o status da notificação na resposta.
falso Padrão. Não retorne o status do dispositivo nem o da notificação.

X-WNS-Tag

Atribui uma etiqueta de rótulo a uma notificação. A tag é utilizada na política de substituição do bloco de notificação na fila de notificações quando o aplicativo optou por ciclo de notificações. Se uma notificação com essa marca já existir 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 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 posteriormente a 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 no esquema de substituição de notificação normal.

X-WNS-TTL: <integer value>

Valor Descrição
valor inteiro O período de vida 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 de uma notificação toast, enviando 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: verdadeiro | falso

Valor Descrição
verdadeiro Envie a notificação de brinde diretamente para a central de ações; não crie a interface de notificação de brinde.
falso Padrão. Crie a interface do usuário do sistema, bem como adicione a notificação à central de ações.

X-WNS-Group

Observação

A central de ações para aplicativos da Windows Phone Store só poderá exibir várias notificações do sistema com a mesma marca se forem rotuladas como pertencentes a grupos diferentes. Por exemplo, considere um aplicativo de livro de receitas. Cada receita seria identificada por uma etiqueta. Um brinde que contém um comentário sobre essa receita teria a marca da receita, mas um rótulo de grupo de comentários. Um brinde 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 toast fossem mostradas de uma só vez na Central de Ações. Esse cabeçalho é opcional.

Grupo X-WNS: <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 específica, um conjunto de notificações (por marca ou grupo) ou todas as notificações do centro de ações para aplicativos da Windows Phone Store. 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 carga incluída nessa solicitação de notificação é ignorada.

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; todo

Valor Descrição
type:wns/toast; group=<string value>; tag=<string value> Remova uma única notificação rotulada com a etiqueta e o grupo especificados.
type:wns/toast; group=<string value> Remova todas as notificações rotuladas com o grupo especificado.
type:wns/toast; tag=<string value> Remova todas as notificações rotuladas com a marca especificada.
type:wns/toast; todo Limpe todas as notificações do aplicativo na 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 Obrigatório Descrição
X-WNS-Debug-Trace FALSO Informações de depuração que devem ser registradas para ajudar na resolução de problemas ao relatar um problema.
X-WNS-DeviceConnectionStatus FALSO O status do dispositivo é retornado apenas se for solicitado na solicitação de notificação por meio do cabeçalho X-WNS-RequestForStatus.
X-WNS-Error-Description FALSO Uma mensagem de erro legível por humanos que deve ser registrada para ajudar na depuração.
X-WNS-Msg-ID FALSO 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 FALSO 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 FALSO Informações de depuração que devem ser registradas para ajudar na resolução de problemas ao relatar 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. Esse cabeçalho, juntamente com o cabeçalho X-WNS-Msg-ID e MS-CV, são necessários ao relatar um problema ao WNS.

X-WNS-Depuração-Rastreamento: <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: conectado | desconectado | tempdisconnected

Valor Descrição
ligado O dispositivo está online e conectado ao WNS.
Desconectado 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 comutador sem fio em um laptop é desligado. 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 de erro legível por humanos que deve ser registrada para ajudar na depuração.

Descrição do erro X-WNS: <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 para ajudar a depurar problemas. Esse cabeçalho, juntamente com o X-WNS-Debug-Trace e MS-CV, são necessários ao 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 êxito ou falha.

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

Valor Descrição
recebido A notificação foi recebida e processada pelo WNS. Observação: isso não garante que o dispositivo recebeu a notificação.
Deixou cair A notificação foi descartada explicitamente 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.
canal limitado A notificação foi descartada porque o servidor de aplicativos excedeu o limite de taxa para esse canal específico.

MS-CV

Esse cabeçalho fornece um Vetor de Correlação relacionado à solicitação que é usada 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á novamente 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.

Importante

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

MS-CV: <string value>

Valor Descrição
valor da cadeia de caracteres Segue o padrão de 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. Nenhum necessário.
400 Solicitação Inválida 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 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 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 sejam autenticados. 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 este canal; as notificações para esse endereço falharão.
Método 405 não permitido Método inválido (GET, CREATE); somente POST (Windows ou Windows Phone) ou DELETE (somente Windows Phone) é permitido. Registre os detalhes da solicitação. Alterne para usar HTTP POST.
406 Não Aceitável O serviço de nuvem excedeu seu limite de limitação. Envie sua solicitação após o valor do cabeçalho Retry-After na resposta
410 Desaparecidos O canal expirou. Registre os detalhes da solicitação. 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 de notificações por push.
413 Entidade de Solicitação Muito Grande O conteúdo da notificação excede o limite de tamanho de 5.000 bytes. Registre os detalhes da solicitação. Inspecione a carga útil para garantir que ela esteja dentro das limitações de tamanho.
500 Erro interno do servidor 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.
Serviço 503 indisponível No momento, o servidor não está disponí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 sem suporte

A Interface da Web WNS dá suporte a HTTP 1.1, mas não dá suporte aos seguintes recursos:

  • Chunking
  • Pipelining (POST não é idempotente)
  • Embora tenha suporte, os desenvolvedores devem desabilitar o Expect-100, pois isso introduz latência ao enviar uma notificação.