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

A API do Graph permite que você assine as alterações em um recurso, incluindo a 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.

• contato
• event
• message

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 suas contrapartes de leitura/gravação), pois elas não dão suporte à assinatura para notificações de alteração 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.

Caminho do recurso

O valor do recurso identifica a caixa de correio na qual assinar, por exemplo users/{id}/messages. Forneça um identificador de usuário que resolva como uma caixa de correio única e inequívoca; caso contrário, a criação da assinatura poderá falhar intermitentemente com um 503 ServiceUnavailable erro, como "As informações da caixa de correio estão obsoletas".

Se você preferir usar um UPN e o UPN começar com um GUID, como 3f8c2a71-6d45-4e9b-a237-81c5f0d762ae@contoso.com, a parte antes do @ símbolo poderá ser interpretada incorretamente como um GUID de caixa de correio em vez de um UPN. Para evitar isso, prefixe o valor com AAD-UPN: para que ele seja sempre tratado como um UPN. Use o prefixo AAD-UPN: somente quando o valor for o UPN de uma conta corporativa ou de estudante.

Para obter um exemplo que usa o prefixo, consulte o AAD-UPN:Exemplo 2.

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

Para que os dados do recurso sejam incluídos em uma notificação de alteração, você deve especificar as seguintes propriedades, além daquelas que você normalmente 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 pode ser encontrado na tabela de tempo de vida da assinatura.

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 incluem dados do recurso. 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 da mensagem que disparou 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.

"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 usando um UPN que começa com um GUID

O exemplo a seguir assina as notificações de uma mensagem que está sendo criada na caixa de correio de um usuário cujo UPN começa com um GUID. O resource valor usa o prefixo para que o AAD-UPN: Exchange trate o valor como um UPN. Para obter mais informações, consulte Caminho do recurso.

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/AAD-UPN:3f8c2a71-6d45-4e9b-a237-81c5f0d762ae@contoso.com/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/AAD-UPN:3f8c2a71-6d45-4e9b-a237-81c5f0d762ae@contoso.com/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 3: Criar uma assinatura para receber notificações de alteração com dados de recursos 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 4: 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

• Notificações de alteração do Microsoft Graph
• Configurar notificações de alteração que incluam dados de recurso
• Visão geral da API de email do Outlook
• visão geral da API de contatos do Outlook
• Visão geral da API do calendário do Outlook