Obter telemetria de mensagens de notificação

  • Artigo

Esta API fornece telemetria adicional nos estados concluídos das notificações push de envio. Foi concebido para ajudar a monitorizar as notificações push enviadas a partir de um hub. O ID de Notificação que esta API utiliza pode ser obtido a partir do cabeçalho Localização HTTP incluído na resposta da API REST utilizada para enviar a notificação.

Esta funcionalidade de Telemetria Por Mensagem também está disponível para notificações agendadas.

Esta API só está disponível para hubs de notificação de escalão Standard.

Pedir

Método URI do pedido Versão HTTP
GET https://{namespace}.servicebus.windows.net/{NotificationHub}/messages/{notification message ID}?api-version=2016-07 HTTP/1.1

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Cabeçalho do pedido Descrição
Autorização Token de SAS gerado conforme especificado em Autenticação de Assinatura de Acesso Partilhado com o Service Bus.
x-ms-version 2016-07 (Suportado por 2015-01 ou posterior)

Corpo do pedido

Nenhum.

Resposta

A resposta inclui um código de estado HTTP e um conjunto de cabeçalhos de resposta. O corpo da resposta é devolvido com êxito.

Códigos de resposta

Código Descrição
200 A telemetria da mensagem foi obtida com êxito. Os dados telemétricos podem ser uma resposta parcial, consoante o número de dispositivos visados pela mensagem de notificação enviada e até onde a mensagem tem progresso através do nosso sistema para processamento.
400 Não foi possível obter a telemetria da mensagem porque o pedido foi mal formado.
401 Falha de autorização. A chave de acesso estava incorreta.
403 Pedido rejeitado porque esta funcionalidade não está ativada para o SKU. Atualize para Standard.
404 A telemetria não existe. Este erro pode ocorrer quando o ID de notificação é inválido.

Para obter informações sobre códigos de estado, veja Códigos de Estado e Erro.

Cabeçalhos de resposta

Cabeçalho de resposta Descrição
Tipo de conteúdo application/xml; charset=utf-8

Corpo da resposta

O corpo da resposta é um documento NotificationDetails que consiste nos seguintes elementos:

Elemento Descrição
NotificationId O ID transmitido para o pedido que identifica a mensagem de notificação.
Localização URI para a mensagem
Estado Indica o progresso da mensagem. O estado pode ser um dos seguintes valores:
  • Abandonado: o processamento de mensagens foi abandonado. Ocorre quando não foi possível processar a mensagem dentro do período de tempo aceitável. Por predefinição, são 30 minutos.
  • Cancelado: o utilizador cancelou esta mensagem agendada.
  • Concluído: o processamento de mensagens foi concluído.
  • Enqueued: a mensagem foi aceite, mas o processamento ainda não começou.
  • NoTargetFound: não foram encontrados dispositivos para enviar esta mensagem.
  • Processamento: o processamento de mensagens foi iniciado.
  • Agendada: a mensagem está na fila e é enviada na hora agendada.
  • Desconhecido: o processamento de mensagens está num estado desconhecido.
EnqueueTime Indica a hora em que a mensagem foi aceite.
StartTime Indica quando o serviço notification hub começou a funcionar na notificação.
EndTime Indica quando o serviço do hub de notificação terminou o trabalho na notificação.
NotificationBody Corpo da mensagem de notificação original.
TargetPlatforms Indica que plataformas são alvos de notificação. Pode conter os seguintes valores como uma cadeia delimitada por vírgulas:
  • windows
  • apple
  • gcm
  • windowsphone
  • adm
  • baidu
  • template
  • windowstemplate
  • appletemplate
  • gcmtemplate
  • windowsphonetemplate
  • admtemplate
  • baidutemplate
ApnsOutcomeCounts Este elemento está presente para notificações enviadas para o Serviço de Notificação Push da Apple. Contém uma coleção de instâncias de Resultados.
MpnsOutcomeCounts Este elemento está presente para notificações enviadas para o Serviço de Notificação Push da Microsoft. Contém uma coleção de instâncias de Resultados.
WnsOutcomeCounts Este elemento está presente para notificações enviadas para o Serviço de Notificação do Windows. Contém uma coleção de instâncias de Resultados.
GcmOutcomeCounts Este elemento está presente para notificações enviadas para o Google Cloud Messaging. Contém uma coleção de instâncias de Resultados.
AdmOutcomeCounts Este elemento está presente para notificações enviadas para o Amazon Device Messaging. Contém uma coleção de instâncias de Resultados.
Resultado Uma coleção destas instâncias compõe as contagens acima para cada serviço de notificação da plataforma. Cada resultado pode ser uma das contagens nomeadas mencionadas na secção Resultados .
PnsErrorDetailsUri Requer Api-Version 2016-07 e superior utilizado para esta API e a API a enviar a mensagem de notificação.

Os detalhes do Erro PNS só estão totalmente disponíveis após a conclusão da operação de envio associada.

Obtém o URI para um blob que contém erros devolvidos por cada PNS envolvido. Se nenhum erro tiver sido comunicado por um PNS, este membro não será incluído na resposta. Pode utilizar a API de Armazenamento do Azure para ler o blob. Para obter mais informações, veja Introdução ao armazenamento de Blobs do Azure com .NET ou API REST dos Serviços de Armazenamento do Azure. Veja Possíveis erros de PNS:
  • Credenciais PNS inválidas
  • PNS Inacessível
  • BadChannel
  • ExpiredChannel
  • PnsThrottled
  • InvalidToken
  • WrongToken
  • Largado
  • WrongChannel

Resultados

Name Descrição da contagem
AbandonedNotificationMessages Contagem de pedidos de envio para o serviço push que foram ignorados devido a um tempo limite.
BadChannel A comunicação com o serviço push falhou porque o canal era inválido.
ChannelDisconnected Serviço push desligado.
ChannelThrottled O serviço push negou o acesso devido à limitação.
Largado O serviço push indica que a mensagem foi removida.
ExpiredChannel A comunicação com o serviço push falhou porque o canal expirou.
InvalidCredentials As credenciais utilizadas para autenticar no serviço push falharam.
InvalidNotificationSize O pedido push é demasiado grande.
NoTargets Contagem de pedidos que não encontraram nada para enviar.
PnsInterfaceError Falha na comunicação do contrato de serviço push.
PnsServerError O serviço push indicou que ocorreu um erro do seu lado.
PnsUnavailable O serviço push não está disponível.
PnsUnreachable O serviço push não respondeu.
Ignorado Contagem de registos duplicados (o mesmo identificador PNS encontrado, ID de registo diferente).
Com êxito O pedido foi enviado com êxito para alguns dispositivos.
Limitado O serviço push negou o acesso devido à limitação.
UnknownError Ocorreu um erro desconhecido.
WrongToken O identificador PNS não foi reconhecido pelo PNS como um identificador válido.

Eis um exemplo de telemetria do envio de uma notificação para o WNS:

<NotificationDetails xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <NotificationId>{Your message id}</NotificationId>
  <Location>sb://{Your namespace}.servicebus.windows.net/{your hub name}/messages/{your message id}?api-version=2015-04</Location>
  <State>Completed</State>
  <EnqueueTime>2015-11-02T21:19:43Z</EnqueueTime>
  <StartTime>2015-11-02T21:19:43.9926996Z</StartTime>
  <EndTime>2015-11-02T21:19:43.9926996Z</EndTime>
  <NotificationBody>&lt;?xml version="1.0" encoding="utf-16"?&gt;&lt;toast&gt;&lt;visual&gt;&lt;binding template="ToastText01"&gt;&lt;text id="1"&gt;Hello from a .NET App!&lt;/text&gt;&lt;/binding&gt;&lt;/visual&gt;&lt;/toast&gt;</NotificationBody>
  <TargetPlatforms>windows</TargetPlatforms>
  <WnsOutcomeCounts>
    <Outcome>
      <Name>Success</Name>
      <Count>3</Count>
    </Outcome>
    <Outcome>
      <Name>WrongToken</Name>
      <Count>1</Count>
    </Outcome>
  </WnsOutcomeCounts>
  <PnsErrorDetailsUri>{Blob uri}</PnsErrorDetailsUri>
</NotificationDetails>

Consulte também

Enviar uma notificação de modelo
Enviar uma notificação nativa do APNS
Enviar uma notificação nativa do GCM
Enviar uma notificação nativa do MPNS
Enviar uma notificação nativa do WNS