Alterar notificações para recursos do Outlook no Microsoft Graph

  • Artigo

O Microsoft API do Graph permite que você assine alterações em um recurso, incluindo criação, atualização ou exclusão do recurso, e receba notificações por meio de webhooks. Uma assinatura especifica os tipos desejados de alterações para monitorar um recurso específico e inclui uma URL de um ponto de extremidade para receber notificações dessas alterações.

Configurar uma assinatura reduz a sobrecarga de consultar e comparar recursos para deduzir quaisquer alterações. Opcionalmente, você pode especificar na solicitação de assinatura para criptografar e incluir como parte de uma notificação os dados do recurso que foram alterados, salvando uma chamada à API subsequente separada para obter o conteúdo do recurso.

Há um limite máximo de 1000 assinaturas ativas para recursos do Outlook por caixa de correio para todos os aplicativos. Você pode assinar alterações em contatos, eventos ou mensagens na caixa de correio.

Assinar alterações em contatos, calendário ou email

Para assinar as notificações de alteração dos recursos do Outlook, primeiro crie uma assinatura.

Os recursos do Outlook a seguir dão suporte a assinaturas com ou sem dados de recurso no conteúdo alterar notificação.

Criar uma assinatura

Para criar uma assinatura, especifique o recurso do Outlook e o tipo de alterações (criação, atualização ou exclusão) para os quais você deseja receber notificações. Veja um exemplo.

Solicitar permissões

Criar e gerenciar (obter, atualizar e excluir) uma assinatura requer um escopo de leitura para o recurso. Por exemplo, para receber notificações de alteração nas mensagens, seu aplicativo precisa da permissão Mail.Read. As notificações de alteração do Outlook dão suporte a escopos de permissão de aplicativo e delegados. Observe as seguintes limitações:

  • A permissão delegada dá suporte a inscrição de itens em pastas apenas na caixa de correio do usuário conectado. Por exemplo, você não pode usar a permissão delegada Calendars.Read para assinar eventos na caixa de correio de outro usuário.

  • Se inscrever para alterar as notificações de contatos, eventos no Outlook ou mensagens em pastascompartilhadas ou delegadas:

    • Usar a permissão de aplicativos correspondentes para inscrever as alterações dos itens em uma pasta ou uma caixa de correio de qualquer usuários no locatário.
    • Não use as permissões de compartilhamento do Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared e seus equivalentes de leitura/gravação), pois elas não dão suporte à assinatura para alterar notificações em itens em pastas compartilhadas ou delegadas.

Dependendo do recurso, use a permissão menos privilegiada especificada na tabela a seguir para chamar essa API.

Resource Trajetórias dos recursos com suporte Delegado (conta corporativa ou de estudante) Delegada (conta pessoal da Microsoft) Aplicativo
contato Alterações em todas as mensagens na caixa de correio de um usuário:
/me/contacts
/users/{id}/contacts
Alterações nos contatos no contactFolder de um usuário:
/users/{id}/contactFolders/{id}/contacts		 Contacts.Read Contacts.Read Contacts.Read
event Alterações em todas as mensagens na caixa de correio de um usuário:
/me/events
/users/{id}/events		 Calendars.Read Calendars.Read Calendars.Read
message Alterações em todas as mensagens na caixa de correio de um usuário:
/me/messages
/users/{id}/messages
Alterações nas mensagens na mailFolder de um usuário:
/users/{id}/mailFolders/{id}/messages		 Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read

Incluir dados de recurso no conteúdo de notificação

Para ter dados de recurso incluídos em uma notificação de alteração, você deve especificar as seguintes propriedades, além daquelas que normalmente você inclui ao criar uma assinatura:

  • includeResourceData: Defina essa propriedade como true para solicitar explicitamente os dados do recurso.

  • resource: Essa propriedade especifica a URL do recurso. Certifique-se de usar o parâmetro de consulta $select para especificar as propriedades de recurso do Outlook a serem incluídas na carga de notificação.

    Observação

    Não inclua na URL $top, $skip, $orderby, $select=Body,UniqueBodye $expand diferentes de singleValueExtendedProperties ou multiValueExtendedProperties.

  • encryptionCertificate: Essa propriedade contém apenas a chave pública que o Microsoft Graph usa para criptografar dados de recurso. Mantenha a chave privada correspondente para descriptografar o conteúdo.

  • encryptionCertificateId: Essa propriedade é seu próprio identificador para o certificado. Use esse ID para corresponder a cada notificação de alteração cujo certificado foi utilizado para descriptografia.

Consulte um exemplo para assinar a alteração de notificações com dados de recurso do recurso mensagem.

Refinar as condições para uma notificação

Você pode refinar ainda mais as condições de uma notificação usando o parâmetro de consulta $filter. Veja um exemplo.

Uma aplicação comum de $filter é ser notificado após uma alteração em uma propriedade de recurso específica. Por exemplo, você pode usar $filter para assinar mensagens não lidas em uma pasta (a propriedade isRead é false) 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 um recurso mensagem na pasta dispararia uma notificação Updated.

Se você não usar um $filter ao criar a assinatura:

  • 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.
  • Excluir a mensagem resultaria em uma notificação Delete.

Assinar notificações de ciclo de vida

Os recursos contato, eventoe mensagem do Outlook também dão suporte à assinatura de notificações de ciclo de vida. As notificações de ciclo de vida são necessárias caso seu aplicativo tenha suas assinaturas removidas ou perca algumas notificações de alteração. Os aplicativos devem implementar a lógica para detectar e recuperar da perda e retomar o fluxo de notificação de alteração contínua. Para saber mais, consulte assinatura de notificações de ciclo de vida.

Acompanhar o tempo de vida da assinatura

Certifique-se de estender uma assinatura antes que ela expire. O tempo de vida máximo de uma assinatura sem dados de recursos do Outlook é de 4230 minutos (menos de 3 dias) e 1 dia com dados de recurso.

Se você perder a permissão concedida anteriormente para uma assinatura e a assinatura expirar enquanto isso, solicite permissão novamente para criar uma nova assinatura.

Receber cargas de notificação

Dependendo da sua assinatura, as notificações podem incluir dados de recursos. As assinaturas com dados de recurso permitem que você obtenha o conteúdo do recurso junto com a notificação, evitando a sobrecarga de uma chamada à API separada para obter os dados de recursos alterados.

Receber notificações com dados de recursos

A seguir, um exemplo da carga de uma notificação com dados de recurso de um recurso mensagem. As propriedades resource e resourceData correspondem à instância de mensagem que acionou a notificação. Use a propriedade encryptedContent para descriptografar os dados do recurso.

{
    "value": [
      {
        "subscriptionId": "dfd11b2f-8222-4189-9545-4205c95d6235",
        "subscriptionExpirationDateTime": "2021-12-31T16:16:44.9907405+05:30",
        "changeType": "created",
        "resource": "Users('722effaf-0433-4272-9ac4-d5ec11c3cd77')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA=')",
        "clientState": "<<--SpecifiedClientState-->>",
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
        "encryptedContent": {
          "data": "<<--EncryptedContent-->>",
          "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
          "dataSignature": "Qw/9ubWeUYJPWWXvNiGgct2FkNG2MXTRm/BLUpJM66k=",
          "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
          "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "resourceData": {
          "@odata.type": "#microsoft.graph.message",
          "@odata.id": "Users('722effaf-0433-4272-9ac4-d5ec11c3cd77')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA=')",
          "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAGDUR8n\"",
          "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA="
        }
      }
    ]
    "validationTokens": ["<<--ValidationTokens-->>"]
}

Para obter detalhes sobre como validar tokens e descriptografar a carga útil, consulte Definir notificações de alteração que incluem dados de recursos.

A seguir está um exemplo de uma carga de notificação descriptografada. A carga descriptografada está em conformidade com o esquema message do Outlook. A carga é semelhante à retornada por uma operaçãoGET. No entanto, a carga de notificação contém apenas as propriedades especificadas com um parâmetro $select na propriedade resource da assinatura. Cargas de notificação de outros recursos do Outlook, como contato e eventos seguem seus respectivos esquemas.

{
    "receivedDateTime@odata.type":"#DateTimeOffset",
    "receivedDateTime":"2021-12-30T10:53:35Z",
    "subject":"TEST MESSAGE FOR RICH NOTIFICATIONS",
    "bodyPreview":"Hello,\r\n\r\nWhat\u2019s up?\r\n\r\nThanks\r\nMegan",
    "importance@odata.type":"#microsoft.graph.importance",
    "importance":"normal",
    "from": {
        "@odata.type":"#microsoft.graph.recipient",
        "emailAddress": {
            "@odata.type":"#microsoft.graph.emailAddress",
            "name":"Megan Brown",
            "address":"Megan.Brown@microsoft.com"
        }
    }
}

Receber notificações sem dados de recurso

Notificações sem dados de recurso fornecem informações suficientes para fazer chamadas GET para obter o recurso. As assinaturas para notificações sem dados de recursos não exigem um certificado de criptografia, porque os dados reais dos recursos não são enviados.

O exemplo a seguir mostra a carga de uma notificação que corresponde a um recurso mensagem do Outlook. Ela inclui as propriedades resource e resourceData, que representam o recurso que disparou a notificação. Use as propriedades resource e @odata.id para fazer chamadas para o Microsoft Graph e obter o conteúdo do recurso.

Observação

As chamadas GET sempre retornarão o estado atual do recurso. Se o recurso for alterado entre o momento em que a notificação é enviada e a hora em que o recurso é recuperado, a operação retornará o estado do recurso na recuperação.

"value": [
 {
   "subscriptionId": "c6126aa3-0ed8-412f-a988-71e6cee627c4",
   "subscriptionExpirationDateTime": "2022-01-02T03:12:18.2257768+05:30",
   "changeType": "created",
   "resource": "Users/622eaaff-0683-4862-9de4-f2ec83c2bd98/Messages/AAMkAGUwNjQ4ZjIxAAA=",
   "resourceData": {
     "@odata.type": "#Microsoft.Graph.Message",
     "@odata.id": "Users/622eaaff-0683-4862-9de4-f2ec83c2bd98/Messages/AAMkAGUwNjQ4ZjIAAA=",
     "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAGDUUXn\"",
     "id": "AAMkAGUwNjQ4ZjIxAAA="
   },
   "clientState": "<<--SpecifiedClientState-->>",
   "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
 }
]

Exemplos

Exemplo 1: Criar uma assinatura para receber notificações de alteração sem dados de recurso quando o usuário receber uma nova mensagem

O exemplo a seguir solicita uma notificação para uma mensagem que está sendo criada na caixa de correio do usuário.

Solicitação

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages",
    "expirationDateTime": "2021-07-07T21:42:18.2257768+00:00",
    "clientState": "secretClientState"
}

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "5522bd62-7c96-4530-85b0-00b916f6151a",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientState",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-01T21:42:18.2257768Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": null,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": null,
    "encryptionCertificateId": null,
    "notificationUrlAppId": null
}

Exemplo 2: criar uma assinatura para obter notificações de alteração com dados de recurso quando o usuário receber uma nova mensagem

O exemplo a seguir assina notificações com dados de recurso para uma mensagem que está sendo criada na caixa de correio do usuário. As propriedades do recurso message a ser incluído na carga de notificação são especificadas usando o parâmetro de consulta $select.

Solicitação

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages?$select=Subject,bodyPreview,importance,receivedDateTime,from",
    "expirationDateTime": "2022-01-01T21:42:18.2257768+00:00",
    "clientState": "secretClientValue",
    "includeResourceData": true,
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId"
}

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "178eec5f-cf3c-4e7e-8a9c-8640deb5b5c5",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages?$select=Subject,bodyPreview,importance,receivedDateTime,from",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientValue",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-01T12:32:35.1582696Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": true,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId",
    "notificationUrlAppId": null
}

Exemplo 3: criar uma assinatura para obter notificações de alteração com dados de recurso para uma mensagem com base em uma condição

O exemplo a seguir assina notificações com dados de recurso para uma mensagem que está sendo criada na pasta Rascunhos, contendo um ou mais anexos e de alta importância.

Solicitação

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "me/mailfolders('Drafts')/messages?$select=Subject,bodyPreview&$filter=hasAttachments eq true AND importance eq 'High'",
    "expirationDateTime": "2022-01-01T21:42:18.2257768+00:00",
    "clientState": "secretClientValue",
    "includeResourceData": true,
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId"
}

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "239dbc5f-cf3c-4e7e-8c9c-3340abc5b5c5",
    "resource": "me/mailfolders('Drafts')/messages?$select=Subject,bodyPreview&$filter=hasAttachments eq true AND importance eq 'High'",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientValue",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-20T12:32:35.1582696Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": true,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId",
    "notificationUrlAppId": null
}

Conteúdo relacionado