Referência da API REST de Notificações de Fluxo de Contínuo do Outlook (versão prévia)

  • Artigo

Aplica-se a: 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 de fluxo contínuo 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 versão v2.0 é a preferida no momento.

A API REST de Notificações de Fluxo de Contínuo do Outlook envia notificações em uma conexão direta para permitir que aplicativos clientes aprendam sobre alterações nos dados da caixa de correio do usuário. Esses dados podem estar nos dados de email, calendário, contato ou tarefa do usuário, protegidos pelo Active Directory do Azure no Office 365 ou 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.

Visão geral

O serviço de notificações por fluxo contínuo do Office 365 estabelece uma conexão direta com um cliente e fornece notificações de alterações de dados solicitadas por um aplicativo cliente.

Quando um aplicativo se inscreve para notificações de um tipo de evento de alteração em um recurso específico (como mensagens na Caixa de Entrada do usuário), uma conexão longa é estabelecida entre o servidor do Office 365 e o cliente. Quando ocorre um evento de disparo (como uma nova mensagem na Caixa de Entrada), o serviço do Office 365 transmite uma notificação para o cliente. O cliente analisa a notificação e executa ações de acordo com sua lógica de negócios, como obter a nova mensagem e atualizar a contagem não lida.

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 notificações de fluxo contínuo e por push. notificações. As notificações por push exigem que o cliente forneça um serviço web de ouvinte para receber notificações do servidor do Office 365, enquanto as notificações de fluxo contínuo exigem apenas uma conexão direta entre o cliente e o servidor do Office 365. Quando uma conexão com o servidor é estabelecida, a conexão permanece aberta por um período especificado. Durante esse tempo, o cliente publica uma solicitação GetNotifications longa apenas uma vez; sempre que um evento de gatilho ocorre, o servidor pode simplesmente enviar uma notificação como parte do fluxo de resposta. Isso continua até que a conexão expire, o cliente desconecte a conexão ou ocorra um problema na rede.

Use a API REST de Notificações de Fluxo Contínuo

Autenticação

Para assinar, receber e fechar notificações, especifique os escopos apropriados para os tipos de recursos para os quais você deseja ser notificado.

Escopo mínimo necessário

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

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

Saiba mais aqui 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.

Versão da API

Atualmente, esta API está no status de versão prévia e está disponível apenas no ponto de extremidade da API REST da versão beta:

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

Usuário de destino

As solicitações da API de Notificações por Fluxo Contínuo são sempre realizadas em nome do usuário atual.

Operações de notificação de fluxo contínuo

Assinar para receber alterações no meu email, calendário, contatos ou tarefas

Assina notificações de fluxo contínuo quando emails, eventos de calendário, contatos ou tarefas são alterados em uma caixa de correio do Office 365 ou do 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

Especifique no corpo da solicitação as seguintes propriedades necessárias para uma solicitação de assinatura de fluxo contínuo. Para mais informações, consulte Entidades de Notificação.

  • odata.type - Incluir "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription".

  • ChangeType - Especifica os tipos de eventos a serem monitorados para esse recurso. Veja ChangeType para os tipos suportados.

  • Resource - Especifica o recurso para monitorar e receber notificações. Você pode usar parâmetros de consulta opcionais, $filter ou $select, para refinar as condições para uma notificação ou 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

Se a solicitação de assinatura for bem-sucedida, uma ID de assinatura será retornado. Por padrão, essa ID de assinatura expira em 90 minutos, a menos que o cliente comece a ouvir notificações em uma conexão. Portanto, enquanto a conexão estiver aberta, a assinatura será renovada automaticamente.

Exemplo de solicitação de assinatura

A solicitação a seguir cria uma assinatura de fluxo contínuo para alterações criadas, atualizadas e excluídas para a caixa de entrada do usuário.

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

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
   ChangeType: "Created,Updated,Deleted"
}

Exemplo de resposta de assinatura

Uma resposta bem-sucedida retorna o HTTP 201 e inclui a ID da assinatura. Este é um exemplo de resposta:

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('RUM4OEJFNUIQUQ4MQ==')",
    "Id":"RUM4OEJFNUIQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Refinar as condições de notificação

Você pode limitar as notificações a um subconjunto de itens usando uma $filter cláusula. Por exemplo, a solicitação de assinatura a seguir cria uma assinatura que aciona uma notificação somente quando são feitas alterações nas mensagens com o campo de assunto "Suplementos".

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

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
   ChangeType: "Created,Updated,Deleted"
}

Uma resposta de assinatura bem sucedida será semelhante a esta:

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('MjcwOUQ2MjEtQUQ4MQ==')",
    "Id":"MjcwOUQ2MjEtQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Inscrever-se para notificações avançadas de fluxo contínuo

Uma assinatura configurada para que uma coleção de recursos retorne o ID de uma instância de recurso que foi alterada. Você precisa obter separadamente as propriedades dessa instância. O primeiro pedido de assinatura acima é um exemplo desse tipo de assinatura. O fluxo de notificação na próxima seção mostra apenas a ID do recurso que é retornado em uma notificação.

Você pode alternativamente usar um $select parâmetro na solicitação de assinatura, especificar as propriedades nas quais você está interessado e também ter esses valores de propriedade retornados nas notificações de fluxo contínuo.

Este é um exemplo que solicita notificações por fluxo contínuo para incluir a propriedade Subject quando um evento é criado:

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

{
    @odata.type:"#Microsoft.OutlookServices.StreamingSubscription",
    Resource: "https://outlook.office.com/api/beta/me/events?$select=Subject",
    ChangeType: "Created"
}

Depois de inscrever-se com sucesso em notificações avançadas de fluxo contínuo, escute as notificações para obter a propriedade Assunto em conteúdos de notificação avançada.

Ouvir as notificações

O cliente cria uma conexão POST pendente de longa duração para as assinaturas especificadas, para solicitar que o servidor inicie as notificações de fluxo contínuo.

POST https://outlook.office.com/api/beta/Me/GetNotifications

Esta solicitação POST não é concluída até que o ConnectionTimeoutinMinutes especificado seja atingido e o servidor termine o blob JSON na resposta, ou se houver outros problemas e o cliente ou o servidor fecharem a conexão.

Enquanto a conexão estiver aberta, todas as assinaturas usando a conexão serão renovadas automaticamente. Se a conexão terminar, essas assinaturas também expirarão em 90 minutos, a menos que o cliente configure uma nova conexão para essas assinaturas.

Certifique-se de que o código que faz essa solicitação POST manipule o código de status de retorno HTTP 404 Not found, que seria retornado se uma assinatura especificada tivesse expirado. Se isso acontecer, solicite uma nova assinatura antes de ouvir suas notificações novamente.

Parâmetro obrigatório do corpo Tipo Descrição
ConnectionTimeoutInMinutes int32 O número de minutos em que a conexão deve permanecer ativa.
KeepAliveNotificationIntervalInSeconds int32 O intervalo usado pelo servidor para enviar notificações keep alive, para notificar o cliente de que a conexão permanece aberta.
SubscriptionIds ​Collection(String)​ IDs das assinaturas que serão notificadas nesta conexão.

Exemplo de solicitações de escuta

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

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg=="
   ]
}

Você pode usar a mesma conexão longa para ouvir notificações de várias assinaturas incluindo mais de uma ID de assinatura na solicitação POST.

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

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg==",
       "Dc4NS04MTg2LUYwRjFFNUVFNTNDRgN0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtN=="
   ]
}

Exemplo de notificação de fluxo

Depois que o serviço é configurado, o cliente recebe o início do blob JSON das notificações.

{
    {"@odata.context":"https://outlook.office.com/api/beta/metadata#Notifications", 
    "value": [

O servidor envia uma notificação keep alive em intervalos fixos para manter a conexão aberta e ativa. Esse intervalo é definido pelo cliente na propriedade KeepAliveNotificationIntervalInSeconds. O formato da notificação keep alive é o seguinte:

{
    "@odata.type": "#Microsoft.OutlookServices.KeepAliveNotification",
    "Status": "OK"
}

Quando ocorre uma alteração controlada no servidor, o servidor envia uma notificação ao cliente por meio da conexão. Em cada notificação, o servidor define a SubscriptionExpirationDateTime propriedade, e continua renovando-a enquanto a notificação anterior for bem-sucedida.

{ 
    "@odata.type": "#Microsoft.OutlookServices.Notification",
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    "SubscriptionExpirationDateTime": "2016-09-09T18:36:42.3454926Z",
    "SequenceNumber": 9, 
    "ChangeType": "Created", 
    "Resource": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
    "ResourceData": { 
        "@odata.type": "#Microsoft.OutlookServices.Message", 
        "@odata.id": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
        "@odata.etag": "W/\"CQAAABYAAAB+0z/4Ly/1ToDr5FGl5k99AAABl5Do\"", 
        "Id": "AAMkADdlAA=" 
    } 
}

Quando seu aplicativo estiver atendendo a várias notificações na mesma conexão longa, você poderá usar o campo SubscriptionId para determinar qual assinatura enviou a notificação.

Observação

A segunda notificação e as notificações subsequentes enviadas a partir do servidor têm uma vírgula inicial antes do colchete de abertura para tornar a notificação válida no JSON.

,{
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    ...
}

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

Se a sua solicitação de assinatura especificar que determinadas propriedades sejam retornadas, as cargas de notificação incluirão os valores dessas propriedades. De acordo com o exemplo acima para inscrever-se em notificações avançadas, um conteúdo de notificação avançada que inclui a propriedade Subject pode ser assim:

{
  "@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"
      }
    }
  ]
}

Feche a conexão

Quando o tempo limite especificado na propriedade ConnectionTimeoutInMinutes é atingido, o servidor fecha a conexão e envia o fim do blob JSON, da seguinte maneira.

    ]
}

A conexão pode ser descartada em outras circunstâncias, como problemas de rede e alterações no servidor, como reinicializações. O cliente pode usar as notificações keep alive para determinar se a conexão ainda está ativa ou foi descartada. Neste último caso, o cliente deve tentar se reconectar usando a ID de assinatura existente. Se a ID de assinatura expirou, uma nova solicitação de assinatura deverá ser feita para restabelecer a conexão.

Se o cliente não quiser mais ouvir uma assinatura, o cliente pode cancelar a solicitação POST e cancelar a conexão. Da próxima vez que o servidor tentar enviar uma notificação, ele receberá um erro, detectará a queda da conexão, interromperá as notificações de manutenção e fechará a conexão.

Entidades de notificação e enumerações

Assinatura

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

Tipo base: Entity

Propriedade Tipo Descrição É gravável? Filtráveis
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.

Tipo base: Entity

Propriedade Tipo Descrição É gravável? Filtráveis
SubscriptionId sequência de caracteres Identificador único para a assinatura. Não N/D
SequenceNumber int32 Indica o valor da sequência da notificação de alteração. Não N/D
Changetype sequência de caracteres Indica o tipo de evento que gerou a notificação. Veja ChangeType para os tipos suportados. Não N/D
Recurso sequência de caracteres Especifica o item de recurso que está sendo monitorado para alterações Não N/D
ResourceData Entidade Identifica a entidade que mudou. Esta é uma propriedade de navegação Não N/D

Changetype

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

Valores com suporte:

  • Confirmado
  • Criado
  • Excluído
  • Perdido. Uma notificação Missed ocorre quando o serviço de notificações não consegue enviar a notificação solicitada.
  • Atualizado

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: