Referência da API REST de notificações por push do Outlook (beta)

Aplica-se ao: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Observação

Esta versão da documentação cobre a API de notificações por push em versão prévia. Os recursos de versão prévia estão sujeitos a alterações antes da finalização e podem fazer com que seu código deixe de funcionar. Por essa razão, em geral, você deve usar somente uma versão de produção de uma API em seu código de produção. Se disponível, a v2.0 é, no momento, a versão preferida.

A API REST das notificações por push do Outlook envia notificações a um serviço Web do lado do cliente para permitir que os aplicativos aprendam sobre alterações nos dados da caixa de correio de um usuário. Essas alterações podem ocorrer nos dados de email, calendário, contato ou tarefa do usuário, protegidos pelo Active Directory do Azure no Office 365 e em dados semelhantes nas contas da Microsoft, especificamente nestes domínios: Hotmail.com, Live.com, MSN.com, Outlook.com e Passport.com.

Observação

Para simplificar a referência, o restante deste artigo usa o Outlook.com para incluir esses domínios de conta da Microsoft.

Não tem interesse na versão beta da API? No sumário à esquerda, vá para a seção de Referência da API REST do Office 365 e selecione a versão desejada.

Visão geral

A API e o serviço de notificações por push do Office 365 funcionam com clientes que fornecem um serviço Web com um endereço de retorno de chamada e usam webhooks para fornecer notificações a aplicativos clientes. Os webhooks são retornos de chamada HTTP configurados geralmente por um serviço Web confiável de back-end de terceiros. O serviço Web pode configurar webhooks para fazer com que os eventos de acionamento em um site chamem o comportamento em outro.

Quando um aplicativo assina o recebimento de notificações de um recurso específico (como mensagens na Caixa de Entrada do usuário), ele especifica uma URL de retorno de chamada de webhook na solicitação de assinatura. Quando ocorre um evento de acionamento (como uma nova mensagem na Caixa de Entrada), o serviço de notificação do Office 365 envia uma notificação por meio de um webhook para a URL de retorno de chamada. O aplicativo, por sua vez, executa ações de acordo com sua lógica de negócios, como obter a nova mensagem e atualizar a contagem não lida.

Os aplicativos devem renovar suas assinaturas antes que elas expirem. Eles também podem cancelar a assinatura a qualquer momento para deixar de receber notificações.

Comparar fluxo contínuo e notificações por push

Os aplicativos de email, calendário e CRM geralmente usam notificações para atualizar seu cache local, exibições de cliente correspondentes ou sistema de back-end após as alterações. O Outlook oferece suporte a fluxo contínuo e notificações por push. Atualmente, as notificações por push são comumente usadas por aplicativos móveis, uma vez que não exigem que os clientes pesquisem as alterações e lhes disponibilizam atualizações quase que imediatamente.

Na comparação, as notificações por push exigem que o cliente forneça seu próprio serviço Web para receber notificações, enquanto as notificações por fluxo contínuo exigem apenas uma conexão direta entre o cliente e o serviço de notificações por fluxo contínuo do Office 365.

Usar a API REST de notificações por push

Autenticação

Para se inscrever, consultar, renovar e excluir assinaturas, especifique os escopos apropriados para os tipos de recursos sobre os quais você deseja ser notificado.

Escopo mínimo necessário

Um dos escopos de leitura a seguir correspondente ao recurso de destino:

Como outra API REST do Outlook, você deve incluir um token de acesso válido a cada solicitação à API de notificações por push do Outlook. Para obter um token de acesso você deve ter registrado e identificado o seu aplicativo e obtido a autorização adequada.

Você pode saber mais sobre algumas opções simplificadas de registro e autorização. Tenha isso em mente ao prosseguir com as operações específicas na API de notificações por push.

Versão da API

Essa API foi promovida da versão prévia para o status de Disponibilidade Geral (GA). Há suporte nas versões v2.0 e beta da API REST do Outlook.

Usuário de destino

As solicitações da API de notificações por push são sempre realizadas em nome do usuário atual.

Veja Usar a API REST do Outlook para obter mais informações comuns a todos os subconjuntos da API REST do Outlook.

Operações de notificação por push

Assinar as alterações no meu e-mail, calendário, contatos ou tarefas

Processo de assinatura

O processo de assinatura funciona assim:

  1. Um aplicativo cliente faz uma solicitação de assinatura (POST) para um recurso específico. Inclui uma URL de notificação, entre outras propriedades.

  2. O serviço de notificações do Outlook tenta validar a URL de notificação com o serviço de ouvinte. Inclui um token de validação na solicitação de validação.

  3. Se o serviço de ouvinte validar a URL com êxito, ele retornará uma resposta de sucesso dentro de 5 segundos, da seguinte maneira:

    • Define o tipo de conteúdo no cabeçalho de resposta para texto\simples.
    • Inclui o mesmo token de validação no corpo da resposta.
    • Retorna um código de resposta HTTP 200. O ouvinte pode descartar o token de validação posteriormente.
  4. Dependendo do resultado da validação da URL, o serviço de notificações do Outlook envia uma resposta ao aplicativo cliente:

    • Se a validação da URL for bem-sucedida, o serviço criará a assinatura com uma ID de assinatura única e enviará a resposta ao cliente.
    • Se a validação de URL não for bem-sucedida, o serviço enviará uma resposta de erro com um código de erro e outros detalhes.
  5. Ao receber uma resposta bem-sucedida, o aplicativo cliente armazena o ID da assinatura para correlacionar futuras notificações a essa assinatura.

Pedido de assinatura

Assina um serviço de ouvinte para receber notificações quando emails, eventos de calendário, contatos ou tarefas são alterados no Office 365 ou no Outlook.com. Este é o primeiro passo para um cliente começar a receber notificações de um recurso (uma entidade ou coleção de entidades).

POST https://outlook.office.com/api/beta/me/subscriptions

No corpo da solicitação, especifique as propriedades a seguir, necessárias para uma solicitação de assinatura por push. Exceto para ClientState, todas as propriedades são necessárias. Para mais informações, veja Entidades de Notificação.

  • odata.type - Incluir "@odata.type":"#Microsoft.OutlookServices.PushSubscription". A entidade PushSubscription define NotificationURL.
  • ChangeType  – especifica os tipos de eventos a serem monitorados para esse recurso. Veja ChangeType para saber os tipos suportados.
  • ClientState – propriedade opcional que indica que cada notificação deve ser enviada com um cabeçalho pelo mesmo valor ClientState. Isso permite que o ouvinte verifique a legitimidade de cada notificação.
  • NotificationURL  – especifica para onde as notificações devem ser enviadas. Essa URL representa um serviço Web normalmente implementada pelo cliente.
  • Resource  – especifica o recurso a ser monitorado e receber notificações. É possível usar parâmetros de consulta opcionais, $filter, para refinar as condições para uma notificação, ou $select, para incluir propriedades específicas em uma notificação avançada.

A seguir estão os recursos suportados:

  • Uma pasta ou pasta de pesquisa comum para mensagens, eventos, contatos ou tarefas. Como exemplos:

    https://outlook.office.com/api/beta/me/mailfolders('inbox')/messages

    https://outlook.office.com/api/beta/me/taskfolders('{folder_id}')/tasks

  • Ou uma coleção de entidades de nível superior, mensagens, eventos, contatos ou tarefas, como:

    https://outlook.office.com/api/beta/me/messages

    https://outlook.office.com/api/beta/me/events

    https://outlook.office.com/api/beta/me/contacts

    https://outlook.office.com/api/beta/me/tasks

Exemplo de solicitação de assinatura

O exemplo a seguir mostra como se inscrever em novos eventos.

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
   "Resource": "https://outlook.office.com/api/beta/me/events",
   "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",  
   "ChangeType": "Created",
   "ClientState": "c75831bd-fad3-4191-9a66-280a48528679"
}

Refinar as condições para notificação

É possível refinar ainda mais as condições para uma notificação usando o parâmetro de consulta $filter.

O exemplo a seguir solicita uma notificação para uma Mensagem sendo criada na pasta Rascunhos, contendo um ou mais anexos e com a importância  High:

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1 
Content-Type: application/json 
 
{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/me/mailfolders('Drafts')/messages?$filter=HasAttachments%20eq%20true%20AND%20Importance%20eq%20%27High%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Has attachments and high importance" 
} 

O exemplo a seguir solicita uma notificação para um Evento de dia inteiro sendo criado:

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1 
Content-Type: application/json 
 
{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/me/events?$filter=IsAllDay%20eq%20true", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Notifications for events that IsAllDay." 
} 

O exemplo a seguir solicita uma notificação para um Contato sendo criado com a empresa sendo Contoso:

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1 
Content-Type: application/json 
 
{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/me/contacts?$filter=CompanyName%20eq%20%27Contoso%27", 
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient", 
  ChangeType: "Created", 
  ClientState: "Contacts in Contoso." 
} 

Uma aplicação comum de $filter é para obter uma notificação sobre uma alteração em uma propriedade específica do recurso especificado. Por exemplo, você pode usar $filter para se inscrever em mensagens não lidas em uma pasta (a propriedade IsRead é falsa) e inclui todos os tipos de alteração:

  • Uma mensagem adicionada ou marcada como não lida na pasta dispararia uma notificação Created.
  • Ler uma mensagem ou marcá-la como lida na pasta dispararia uma notificação Deleted.
  • Uma alteração em qualquer propriedade, diferente de IsRead, de uma mensagem na pasta dispararia uma notificação Updated.

É possível criar uma assinatura da seguinte maneira:

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/beta/me/mailfolders('folder_id')/messages$filter=IsRead%20eq%20false",
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

Caso não use $filter ao criar a assinatura (conforme abaixo):

  • Adicionar uma mensagem à pasta resultaria em uma notificação Created.
  • Ler uma mensagem na pasta, marcar a mensagem como lida ou alterar qualquer outra propriedade de uma mensagem nessa pasta resultaria em uma notificação Updated.
  • A exclusão da mensagem resultaria em uma notificação Delete.
POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/beta/me/mailfolders('folder_id')/messages,
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

Solicitação de validação

A solicitação de validação tenta validar a NotificationURL que um aplicativo cliente especifica em uma solicitação de assinatura:

POST https://{notificationUrl}?validationToken={token}

O serviço do Outlook especifica o NotificationURL na solicitação de assinatura em {notificationUrl} e define uma sequência de caracteres {token} como o token de validação. O serviço do Outlook também inclui o cabeçalho ClientState se o aplicativo cliente incluir um no pedido de assinatura.

Resposta da assinatura

A resposta da assinatura inclui as propriedades na solicitação e as seguintes propriedades adicionais:

  • Id – a ID única de assinatura que o aplicativo cliente deve salvar para corresponder às notificações futuras.
  • ChangeType – além dos valores especificados na solicitação, a resposta inclui o tipo de notificação adicional, Perdido.
  • SubscriptionExpirationDateTime – a data e a hora em que a assinatura expirará. Se a solicitação de assinatura não especificar um prazo de expiração ou especificar um tempo de expiração maior que o máximo permitido, essa propriedade será definida com o tamanho máximo permitido a partir do momento em que a solicitação é enviada. Para uma assinatura que solicita notificações avançadas de propriedades específicas, o máximo permitido é de 1 dia. Para outras assinaturas, o máximo é de 7 dias.
  • Outras propriedades relacionadas ao OData.

Exemplo de resposta de assinatura

Essa resposta indica que o serviço de ouvinte deve esperar receber notificações de novos eventos e alterações perdidas. Se houver alterações perdidas, o cliente precisará sincronizar com o serviço para capturá-las.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')",
    "Id": "Mjk3QNERDQQ==",
    "Resource": "https://outlook.office.com/api/beta/me/events",
    "ChangeType": "Created, Missed",
    "ClientState": "c75831bd-fad3-4191-9a66-280a48528679",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
    "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z"
}

Pesquisar uma assinatura

É possível encontrar detalhes sobre qualquer uma das assinaturas existentes do usuário conectado especificando o ID da assinatura. Por exemplo, para consultar a assinatura criada no último exemplo:

GET https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')

Se tiver êxito, a resposta seria igual aos dados de resposta do último exemplo, exceto que ela excluiria qualquer ClientState que o aplicativo cliente tivesse especificado para evitar possíveis riscos de segurança.

Notificações

Cada notificação contém as seguintes propriedades, independentemente do seu tipo:

  • Cabeçalho ClientState – presente somente caso o cliente tenha especificado a propriedade ClientState na solicitação de assinatura. Usado pelo ouvinte para verificar a legitimidade da notificação.
  • SubscriptionId – identifica, para o aplicativo cliente, a assinatura à qual esta notificação pertence.
  • SubscriptionExpirationDateTime – a data e hora de expiração da assinatura.
  • SequenceNumber – um número em sequência para uma notificação para ajudar o aplicativo cliente a identificar se está faltando uma notificação.
  • ChangeType – os tipos de eventos sobre os quais o aplicativo cliente deseja ser notificado (por exemplo, um tipo de evento Criado quando o email é recebido ou um tipo de evento Atualizar ao ler uma mensagem).
  • Resource – a URL do item de recurso específico que está sendo monitorado (por exemplo, uma URL para a mensagem ou evento alterados).
  • ResourceData – uma notificação relacionada a uma alteração de recurso (como receber, ler ou excluir uma mensagem) tem essa propriedade adicional que contém a identificação do recurso do item que foi alterado. Um cliente pode usar essa identificação do recurso para manusear esse item de acordo com sua lógica de negócios (por exemplo, buscar esse item, sincronizar sua pasta).

Observação

A propriedade Id não é utilizada em entidades do tipo Notification.

Alterar conteúdo da notificação

No exemplo a seguir, assim que o usuário recebe um novo evento, o serviço de notificações envia uma notificação com o ChangeType definido como “Criado”. O cabeçalho da notificação incluiria o ClientState conforme especificado na solicitação de assinatura inicial. A notificação de evento recebida possui um conteúdo semelhante a este:

{
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.Notification",
            "Id": null,
            "SubscriptionId": "Mjk3QNERDQQ==",
            "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z",
            "SequenceNumber": 1,
            "ChangeType": "Created",
            "Resource" : "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
            "ResourceData": {
                "@odata.type": "#Microsoft.OutlookServices.Event",
                "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
                "Id": "AAMkADNkNmAA="
            }
        }
    ]
}

Obter propriedades de instância assinando notificações avançadas

Como visto no exemplo anterior de um conteúdo de notificação alterado, uma assinatura de notificação por push configurada para uma coleção de recursos retorna apenas o ID de uma instância de recurso que foi alterada. Você precisa obter separadamente as propriedades dessa instância.

É possível salvar uma chamada API GET separada usando um parâmetro $select na solicitação de assinatura e especificando as propriedades nas quais você está interessado. Este é um exemplo que solicita uma notificação para incluir a propriedade subject quando um evento foi criado:

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
    "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
    "Resource": "https://outlook.office.com/api/beta/me/events?$select=Subject",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myRichNotifyClient",
    "ChangeType": "Created"
}

Amostra de conteúdo de notificação avançada

Um conteúdo de notificação avançada inclui os valores das propriedades especificadas na solicitação de assinatura. Após o último exemplo, uma notificação avançada inclui a propriedade Subject como esta:

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Notifications",
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "QjQzNzAwBQQ==",
      "SubscriptionExpirationDateTime": "2017-01-18T00:57:28.6134733Z",
      "SequenceNumber": 1,
      "ChangeType": "Created",
      "Resource": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
      "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Event",
        "@odata.id": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

Renovar a assinatura

Renove uma assinatura até o prazo máximo quando a renovação for solicitada.

PATCH https://outlook.office.com/api/beta/me/subscriptions/{subscriptionId}

A duração da assinatura padrão é de 7 dias para solicitações que não exigem propriedades de instância específicas na resposta e de 1 dia para assinaturas de notificações avançadas.

É possível enviar a solicitação de renovação sem um conteúdo, e a assinatura será estendida pelo período máximo correspondente.

Exemplo de solicitação

PATCH https://outlook.office.com/api/beta/me/subscriptions/Mjk3QNERDQQ==

{
   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   "SubscriptionExpirationDateTime": "2015-05-28T17:17:45.9028722Z"
}

Resposta

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 200.

Excluir assinatura

Excluir uma assinatura especificando seu ID.

DELETE https://outlook.office.com/api/beta/me/subscriptions('{subscriptionId}')

Exemplo de solicitação

Delete https://outlook.office.com/api/beta/me/subscriptions('Mjk3QNERDQQ==')

Resposta

Uma resposta bem-sucedida é indicada por um código de resposta HTTP 204 No Content.

Entidades e enumerações da API de notificação

Assinatura

Representa a assinatura base. Esta é uma classe base abstrata.

Tipo base: Entity

Propriedade Tipo Descrição Gravável? Filtrável?
Recurso sequência de caracteres Especifica o recurso cujas alterações serão monitoradas. Sim N/D
ChangeType Changetype Indica os tipos de eventos que gerarão uma notificação. Veja ChangeType para saber os tipos suportados. Sim N/D

Notificação

Representa uma notificação enviada ao cliente. No caso de notificações por push, a notificação é enviada ao serviço de ouvinte especificado pelo cliente.

Tipo base: Entity

Propriedade Tipo Descrição Gravável? Filtrável?
SubscriptionId sequência de caracteres Identificador único para a assinatura. Não Não
SubscriptionExpirationDateTime Edm.DateTimeOffset Especifica a data e a hora em que a assinatura de notificação expira. A hora é dada em UTC. Sim N/D
SequenceNumber int32 Indica o valor da sequência da notificação de alteração. Não N/D
ChangeType ChangeType Indica o tipo de evento que gerou a notificação. Os valores de enumeração são: Criado = 1, Atualizado = 2, Excluído = 4, Perdido = 16. Uma notificação perdida ocorre quando o serviço de notificações não consegue enviar a notificação solicitada. Não N/D
Recurso sequência de caracteres Especifica o item de recurso cujas alterações estão sendo monitoradas. Sim N/D
ResourceData Entidade Identifica a entidade que mudou. Essa é uma propriedade de navegação. Não N/D

PushSubscription

Representa uma assinatura que usa o mecanismo de notificação por push.

Tipo base: Assinatura

Propriedade Tipo Descrição Gravável? Filtrável?
NotificationURL sequência de caracteres A URL do aplicativo que receberá as notificações por push. Sim N/D
SubscriptionExpirationDateTime Edm.DateTimeOffset Especifica a data e a hora em que a assinatura de notificação expira. A hora é dada em UTC. Sim N/D
ClientState sequência de caracteres Especifica o valor de ClientState no cabeçalho enviado pelo serviço para cada notificação. O comprimento máximo é de 255 caracteres. O cliente pode verificar se a notificação veio do serviço comparando o valor definido na propriedade ClientState com o valor do cabeçalho ClientState recebido com cada notificação. Sim Não

ChangeType

Uma enumeração que especifica os tipos de eventos que ocorrem nos recursos com suporte que podem gerar uma notificação.

Valores suportados:

  • Acknowledgment
  • Created
  • Excluído
  • Missed. Uma notificação Missed ocorre quando o serviço de notificações não consegue enviar a notificação solicitada.
  • Updated

Próximas etapas

Se você estiver pronto para começar a criar um aplicativo ou apenas quiser aprender mais, temos tudo o que você precisa.

Se preferir, aprenda mais sobre como usar a plataforma do Office 365: