Configurar notificações para alterações nos dados de usuárioSet up notifications for changes in user data

A API do Microsoft Graph usa um mecanismo de webhook para fornecer notificações de alteração aos clientes. Um cliente é um serviço Web que configura sua própria URL para receber notificações. Aplicativos cliente usam notificações de alteração para atualizar seu estado após alterações.The Microsoft Graph API uses a webhook mechanism to deliver change notifications to clients. A client is a web service that configures its own URL to receive change notifications. Client apps use change notifications to update their state upon changes.

Depois que o Microsoft Graph aceita a solicitação de assinatura, ele envia notificações de alteração por push para a URL especificada na assinatura.After Microsoft Graph accepts the subscription request, it pushes change notifications to the URL specified in the subscription. O aplicativo então realiza ações de acordo com sua lógica comercial.The app then takes action according to its business logic. Por exemplo, ele busca mais dados, atualiza o cache e as exibições, etc.For example, it fetches more data, updates its cache and views, and so on.

Por padrão, as notificações de alteração não contêm dados de recursos, exceto o id.By default, change notifications do not contain resource data, other than the id. Se o aplicativo exigir dados de recursos, ele poderá fazer chamadas para as APIs do Microsoft Graph para obter o recurso completo.If the app requires resource data, it can make calls to Microsoft Graph APIs to get the full resource. Este artigo usa o recurso de usuário como um exemplo para trabalhar com notificações de alteração.This article uses the user resource as an example for working with change notifications.

Um aplicativo também pode se inscrever para alterar notificações que incluem dados de recursos, para evitar a necessidade de fazer chamadas de API adicionais para acessar os dados.An app can also subscribe to change notifications that include resource data, to avoid having to make additional API calls to access the data. Esses aplicativos precisarão implementar um código extra para lidar com os requisitos de tais notificações, especificamente: responder às notificações do ciclo de vida da assinatura, validar a autenticidade das notificações e descriptografar os dados do recurso.Such apps will need to implement extra code to handle the requirements of such notifications, specifically: responding to subscription lifecycle notifications, validating the authenticity of notifications, and decrypting the resource data. Para saber mais sobre como trabalhar com essas notificações, confira Configurar notificações de alteração que incluam dados de recurso.For details about how to work with these notifications, see Set up change notifications that include resource data.

Recursos com suporteSupported resources

Usando a API do Microsoft Graph, um aplicativo pode se inscrever para alterações nos seguintes recursos:Using the Microsoft Graph API, an app can subscribe to changes on the following resources:

Você pode criar uma assinatura para uma pasta de específica do Outlook, como a Caixa de Entrada: me/mailFolders('inbox')/messagesYou can create a subscription to a specific Outlook folder such as the Inbox: me/mailFolders('inbox')/messages

Ou para um recurso de nível superior: /me/messages, /me/contacts, /me/events, users, groups, /communications/callRecordsOr to a top-level resource: /me/messages, /me/contacts, /me/events, users, groups, /communications/callRecords

Ou para uma instância de recurso específica: users/{id}, groups/{id}, groups/{id}/conversations, sites/{site-id}/lists/{list-id}, /communications/presences/{id}Or to a specific resource instance: users/{id}, groups/{id}, groups/{id}/conversations, sites/{site-id}/lists/{list-id}, /communications/presences/{id}

Ou para alguma pasta no OneDrive pessoal de um usuário: /drives/{id}/root /drives/{id}/root/subfolderOr to any folder in a user's personal OneDrive: /drives/{id}/root /drives/{id}/root/subfolder

Ou para a pasta raiz de uma unidade do SharePoint/OneDrive for Business: /drive/rootOr to the root folder of a SharePoint/OneDrive for Business drive: /drive/root

Ou para um novo alerta da API de Segurança: /security/alerts?$filter=status eq 'newAlert', /security/alerts?$filter=vendorInformation/provider eq 'ASC'Or to a new Security API alert: /security/alerts?$filter=status eq 'newAlert', /security/alerts?$filter=vendorInformation/provider eq 'ASC'

Ou para as tarefas na Lista de Tarefas Pendentes de um usuário: /me/todo/lists/{todoTaskListId}/tasksOr to the tasks in a user's To Do list: /me/todo/lists/{todoTaskListId}/tasks

Limitações de recursos do Microsoft Azure ADAzure AD resource limitations

Determinadas limites se aplicam aos recursos baseados no Azure AD (usuários, grupos) e gerarão erros se forem excedidos:Certain limits apply to Azure AD based resources (users, groups) and will generate errors when exceeded:

Observação: Esses limites não se aplicam aos recursos de serviços diferente do Azure AD.Note: These limits do not apply to resources from services other than Azure AD. Por exemplo, um aplicativo pode criar muito mais assinaturas para message ou recursos event que são aceitos pelo serviço Exchange Online como parte do Microsoft Graph.For example, an app can create many more subscriptions to message or event resources, which are supported by the Exchange Online service as part of Microsoft Graph.

  • Cotas máximas de assinaturas:Maximum subscription quotas:

    • Por aplicativo (para todos os locatários combinados): 50.000 assinaturas totaisPer app (for all tenants combined): 50,000 total subscriptions
    • Por locatário (para todos os aplicativos combinados): 1000 total de assinaturas em todos os aplicativosPer tenant (for all applications combined): 1000 total subscriptions across all apps
    • Combinação por aplicativo e locatário: 100 assinaturas no totalPer app and tenant combination: 100 total subscriptions

Quando os limites são excedidos, a tentativa de criar uma assinatura resultará em uma resposta de erro - 403 Forbidden.When any limit is exceeded, attempts to create a subscription will result in an error response - 403 Forbidden. A propriedade message explicará qual limite foi excedido.The message property will explain which limit has been exceeded.

  • Não há suporte a locatários do Microsoft Azure AD B2C.Azure AD B2C tenants are not supported.

  • Não há suporte a notificações de alteração para contas Microsoft pessoais.Change notification for user entities are not supported for personal Microsoft accounts.

  • Existe um problema conhecido nas assinaturas de usuários e grupos.A known issue exists with user and group subscriptions.

Limitações de recursos do OutlookOutlook resource limitations

Ao se inscrever em recursos do Outlook, tais como mensagens, eventos ou contatos, se você decidir usar o nome UPN em um caminho de recurso, a solicitação de assinatura pode falhar caso o UPN contenha um apóstrofo.When subscribing to Outlook resources such as messages, events or contacts, if you choose to use the user principal name UPN in the resource path, the subscription request might fail if the UPN contains an apostrophe. Considere usar IDs de usuário de GUID em vez de UPNs para evitar esse problema.Consider using GUID user IDs instead of UPNs to avoid running into this problem. Por exemplo, em vez de usar o caminho de recursos:For example, instead of using resource path:

/users/sh.o'neal@contoso.com/messages

Use:Use:

/users/{guid-user-id}/messages

É permitido um máximo de 1000 assinaturas ativas por caixa de correio para todos os aplicativos.A maximum of 1000 active subscriptions per mailbox for all applications is allowed.

Limitações de recursos do TeamsTeams resource limitations

Cada recurso do Teams possui cotas de assinatura diferentes.Each Teams resource has different subscription quotas.

  • Para assinaturas do callRecords:For subscriptions to callRecords:

    • Por organização: 100 assinaturas totaisPer organization: 100 total subscriptions
  • Para assinaturas de chatMessages (canais ou chats):For subscriptions to chatMessages (channels or chats):

    • Por combinação por aplicativo e canal ou por chat: uma assinaturaPer app and channel or chat combination: 1 subscription
    • Por organização: 10.000 assinaturas totaisPer organization: 10,000 total subscriptions

Tempo de vida da assinaturaSubscription lifetime

As assinaturas têm tempo de vida limitado.Subscriptions have a limited lifetime. Os aplicativos precisam renovar suas assinaturas antes do tempo de expiração.Apps need to renew their subscriptions before the expiration time. Caso contrário, será preciso criar uma nova assinatura.Otherwise, they need to create a new subscription. Confira a lista de prazos máximos em Prazo máximo de assinatura por tipo de recurso.For a list of maximum expiration times, see Maximum length of subscription per resource type.

Os aplicativos também podem cancelar a assinatura a qualquer momento para deixarem de receber notificações de alteração.Apps can also unsubscribe at any time to stop getting change notifications.

Gerenciar assinaturasManaging subscriptions

Os clientes podem criar, renovar e excluir assinaturas.Clients can create subscriptions, renew subscriptions, and delete subscriptions.

Criar uma assinaturaCreating a subscription

Criar uma assinatura é a primeira etapa para começar a receber notificações de alteração de um recurso.Creating a subscription is the first step to start receiving change notifications for a resource. O processo de assinatura ocorre da seguinte maneira:The subscription process is as follows:

  1. O cliente envia uma solicitação de assinatura (POST) para um recurso específico.The client sends a subscription (POST) request for a specific resource.

  2. O Microsoft Graph verifica a solicitação.Microsoft Graph verifies the request.

    • Se a solicitação for válida, o Microsoft Graph enviará um token de validação para a URL de notificação.If the request is valid, Microsoft Graph sends a validation token to the notification URL.
    • Se a solicitação for inválida, o Microsoft Graph enviará uma resposta de erro com um código e detalhes.If the request is invalid, Microsoft Graph sends an error response with code and details.
  3. O cliente envia o token de validação de volta para o Microsoft Graph.The client sends the validation token back to Microsoft Graph.

  4. O Microsoft Graph envia uma resposta de volta para o cliente.The Microsoft Graph sends a response back to the client.

O cliente deve armazenar a ID da assinatura para correlacionar notificações de alteração com a assinatura.The client must store the subscription ID to correlate change notifications with the subscription.

Exemplo de solicitação de assinaturaSubscription request example

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/notificationClient",
  "resource": "/me/mailfolders('inbox')/messages",
  "expirationDateTime": "2016-03-20T11:00:00.0000000Z",
  "clientState": "SecretClientState"
}

As propriedades changeType, notificationUrl, resource e expirationDateTime são obrigatórias.The changeType, notificationUrl, resource, and expirationDateTime properties are required. Confira os valores e as definições de propriedade em tipo de recurso de assinatura.See subscription resource type for property definitions and values.

A propriedade resource especifica o recurso que será monitorado para detectar alterações.The resource property specifies the resource that will be monitored for changes. Por exemplo, você pode criar uma assinatura para uma pasta de email específica: me/mailFolders('inbox')/messages ou em nome de um usuário, atribuído com uma autorização do administrador: users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages.For example, you can create a subscription to a specific mail folder: me/mailFolders('inbox')/messages or on behalf of a user given by an administrator consent: users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages.

Embora clientState não seja obrigatória, você deve incluí-la para manter a conformidade com nosso processo recomendado de manipulação de notificações de alterações.Although clientState is not required, you must include it to comply with our recommended change notification handling process. A definição desta propriedade permitirá confirmar se as notificações de alteração recebidas partiram do serviço do Microsoft Graph.Setting this property will allow you to confirm that change notifications you receive originate from the Microsoft Graph service. Por esse motivo, o valor da propriedade deve continuar em segredo e deve ser conhecido somente por seu aplicativo e pelo serviço do Microsoft Graph.For this reason, the value of the property should remain secret and known only to your application and the Microsoft Graph service.

Se tiver êxito, o Microsoft Graph retornará um código 201 Created e um objeto subscription no corpo.If successful, Microsoft Graph returns a 201 Created code and a subscription object in the body.

Observação: Qualquer parâmetro da cadeia de caracteres de consulta incluído na propriedade notificationUrl será incluído na solicitação de POST HTTP quando as notificações estiverem sendo entregues.Note: Any query string parameter included in the notificationUrl property will be included in the HTTP POST request when notifications are being delivered.

Validação de ponto de extremidade de notificaçãoNotification endpoint validation

O Microsoft Graph valida o ponto de extremidade de notificação fornecido na propriedade notificationUrl da solicitação de assinatura antes de criar a assinatura.Microsoft Graph validates the notification endpoint provided in the notificationUrl property of the subscription request before creating the subscription. O processo de validação ocorre da seguinte maneira:The validation process occurs as follows:

  1. O Microsoft Graph codifica um token de validação e o inclui em uma solicitação POST na URL da notificação:Microsoft Graph encodes a validation token and includes it in a POST request to the notification URL:

    Content-Type: text/plain; charset=utf-8
    POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}
    
  2. O cliente deve realizar a decodificação URL do validationToken fornecido corretamente na etapa anterior e escapar de um HTML/JavaScript.The client must properly URL decode the validationToken query parameter provided in the preceding step, and escape any HTML/JavaScript.

    Escapar é uma boa prática porque atores maliciosos podem usar o ponto de extremidade de notificação para o tipo de ataques de script entre sites.Escaping is a good practice because malicious actors can use the notification endpoint for cross-site scripting type of attacks.

    Em geral, trate o valor do token de validação como opaco, uma vez que o formato do token geralmente pode ser alterado sem aviso.In general, treat the validation token value as opaque, as the token format can generally change without notice. O Microsoft Graph nunca envia nenhum valor contendo código HTML ou JavaScript.Microsoft Graph never sends any value containing HTML or JavaScript code.

  3. O cliente deve fornecer uma resposta com as seguintes características em até 10 segundos da etapa 1:The client must provide a response with the following characteristics within 10 seconds of step 1:

    • Um código de status de HTTP 200 OK.A status code of HTTP 200 OK.
    • Um tipo de conteúdo de text/plain.A content type of text/plain.
    • Um corpo que inclui o token de validação URL decodificada.A body that includes the URL decoded validation token. Basta refletir a mesma cadeia que foi enviada no parâmetro de consulta validationToken.Simply reflect back the same string that was sent in the validationToken query parameter.

    O cliente deve descartar o token de validação depois de o fornecer na resposta.The client should discard the validation token after providing it in the response.

    Importante: se o cliente retornar um token de validação codificado, a validação falhará.Important: If the client returns an encoded validation token, the validation will fail.

Além disso, você pode usar a coleção do Microsoft Graph Postman para confirmar que o ponto de extremidade implementa a solicitação de validação.Additionally, you can use the Microsoft Graph Postman collection to confirm that your endpoint properly implements the validation request. A solicitação de Validação de Assinaturas na pasta Diversos fornece testes de unidade que validam a resposta fornecida por seu ponto de extremidade.The Subscription Validation request in the Misc folder provides unit tests that validate the response provided by your endpoint.

resultados do teste de resposta de validação

Renovar uma assinaturaRenewing a subscription

O cliente pode renovar uma assinatura com uma data de expiração específica de até três dias desde a hora da solicitação.The client can renew a subscription with a specific expiration date of up to three days from the time of request. A propriedade expirationDateTime é obrigatória.The expirationDateTime property is required.

Exemplo de renovação de assinaturaSubscription renewal example

PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
Content-Type: application/json

{
  "expirationDateTime": "2016-03-22T11:00:00.0000000Z"
}

Se tiver êxito, o Microsoft Graph retornará um código 200 OK e um objeto subscription no corpo.If successful, Microsoft Graph returns a 200 OK code and a subscription object in the body. O objeto subscription inclui o novo valor de expirationDateTime.The subscription object includes the new expirationDateTime value.

Excluindo uma assinaturaDeleting a subscription

O cliente pode parar de receber notificações de alteração excluindo a assinatura com o uso de sua ID.The client can stop receiving change notifications by deleting the subscription using its ID.

DELETE https://graph.microsoft.com/v1.0/subscriptions/{id}

Se tiver êxito, o Microsoft Graph retornará um código 204 No Content.If successful, Microsoft Graph returns a 204 No Content code.

Notificações de alteraçãoChange notifications

Com uma assinatura do cliente em um recurso, o Microsoft Graph envia uma solicitação POST para a URL da notificação sempre que o recurso é alterado.With a client subscribing to changes to a resource, Microsoft Graph sends a POST request to the notification URL whenever the resource changes. Notificações são enviadas somente para as alterações do tipo especificado na assinatura, por exemplo, created.It sends notifications only for changes of the type that's specified in the subscription, for example, created.

Observação: se um cliente tiver várias assinaturas que monitoram o mesmo recurso e usam a mesma URL de notificação, o Microsoft Graph poderá enviar várias notificações de alteração que correspondam a diferentes assinaturas, cada uma mostrando a ID da assinatura correspondente.Note: If a client has multiple subscriptions that monitor the same resource and use the same notification URL, Microsoft Graph can send multiple change notifications that correspond to different subscriptions, each showing the corresponding subscription ID. Não há garantias de que todas as notificações na solicitação POST pertencerão a uma única assinatura.There is no guarantee that all change notifications in the POST request belong to a single subscription.

Exemplo de notificação de alteraçãoChange notification example

Esta seção mostra um exemplo de uma notificação para a criação de uma mensagem.This section shows an example of a notification for a message creation. Quando o usuário recebe um email, o Microsoft Graph envia uma notificação de alteração como mostrado no exemplo a seguir.When the user receives an email, Microsoft Graph sends a change notification as shown in the following example. Observe que a notificação está em uma coleção representada no campo value.Note that the notification is in a collection represented in the value field. Confira changeNotificationCollection para obter detalhes da carga de notificação.See changeNotificationCollection for details of the notification payload.

Quando várias alterações ocorrerem, o Microsoft Graph poderá enviar várias notificações que correspondam a diferentes assinaturas na mesma solicitação POST.When many changes occur, Microsoft Graph may send multiple notifications that correspond to different subscriptions in the same POST request.

{
  "value": [
    {
      "id": "lsgTZMr9KwAAA",
      "subscriptionId":"{subscription_guid}",
      "subscriptionExpirationDateTime":"2016-03-19T22:11:09.952Z",
      "clientState":"secretClientValue",
      "changeType":"created",
      "resource":"users/{user_guid}@{tenant_guid}/messages/{long_id_string}",
      "tenantId": "84bd8158-6d4d-4958-8b9f-9d6445542f95",
      "resourceData":
      {
        "@odata.type":"#Microsoft.Graph.Message",
        "@odata.id":"Users/{user_guid}@{tenant_guid}/Messages/{long_id_string}",
        "@odata.etag":"W/\"CQAAABYAAADkrWGo7bouTKlsgTZMr9KwAAAUWRHf\"",
        "id":"{long_id_string}"
      }
    }
  ]
}

Processar a notificação de alteraçãoProcessing the change notification

O processo deve processar todas as notificações de alteração recebidas.Your process should process every change notification it receives. Estas são as tarefas mínimas que o seu aplicativo deve realizar para processar uma notificação de alteração:The following are the minimum tasks that your app must perform to process a change notification:

  1. Envie um código de status 202 - Accepted na sua resposta para o Microsoft Graph.Send a 202 - Accepted status code in your response to Microsoft Graph. Se o Microsoft Graph não receber um código de classe 2xx, ele tentará publicar a notificação de alteração algumas vezes, por um período de aproximadamente 4 horas; depois disso, a notificação será descartada e não será entregue.If Microsoft Graph doesn't receive a 2xx class code, it will try to publishing the change notification a number of times, for a period of about 4 hours; after that, the change notification will be dropped and won't be delivered.

    Observação: Envie um código de status 202 - Accepted assim que receber a notificação de alteração, mesmo antes de validar a sua autenticidade.Note: Send a 202 - Accepted status code as soon as you receive the change notification, even before validating its authenticity. Você está simplesmente confirmando o recebimento da notificação de alteração e impedindo tentativas desnecessárias.You are simply acknowledging the receipt of the change notification and preventing unnecessary retries. O tempo limite atual é de 30 segundos, mas pode ser reduzido no futuro para otimizar o desempenho do serviço.The current timeout is 30 seconds, but it might be reduced in the future to optimize service performance. Se a URL da notificação não responder dentro de 30 segundos para mais de 10% das solicitações do Microsoft Graph durante um período de 10 minutos, todas as notificações a seguir serão adiadas e repetidas por um período de 4 horas.If the notification URL doesn't reply within 30 seconds for more than 10% of the requests from Microsoft Graph over a 10 minute period, all following notifications will be delayed and retried for a period of 4 hours. Se uma URL da notificação não responder dentro de 30 segundos para mais de 20% das solicitações do Microsoft Graph durante um período de 10 minutos, todas as notificações a seguir serão descartadas.If a notification URL doesn't reply within 30 seconds for more than 20% of the requests from Microsoft Graph over a 10 minute period, all following notifications will be dropped.

  2. Validar a propriedade clientState.Validate the clientState property. Ela deve corresponder ao valor enviado originalmente com a solicitação de criação da assinatura.It must match the value originally submitted with the subscription creation request.

    Observação: se isso não for verdadeiro, você não deverá considerar esta notificação como válida.Note: If this isn't true, you should not consider this a valid change notification. É possível que a notificação de alteração não tenha se originado do Microsoft Graph e possa ter sido enviada por um ator invasor.It is possible that the change notification has not originated from Microsoft Graph and may have been sent by a rogue actor. Você também deve investigar de onde vem a notificação de alteração e tomar as medidas apropriadas.You should also investigate where the change notification comes from and take appropriate action.

  3. Atualize seu aplicativo com base na sua lógica comercial.Update your application based on your business logic.

Repita o procedimento para outras notificações de alteração na solicitação.Repeat for other change notifications in the request.

Exemplos de códigoCode samples

Os exemplos de código a seguir estão disponíveis no GitHub.The following code samples are available on GitHub.

Configuração do firewallFirewall configuration

Opcionalmente, você pode configurar o firewall que protege a URL de notificação para permitir conexões de entrada somente pelo Microsoft Graph.You can optionally configure the firewall that protects your notification URL to allow inbound connections only from Microsoft Graph. Isso permite que você reduza ainda mais a exposição a notificações de alteração inválidas que são enviadas para sua URL de notificação.This allows you to reduce further exposure to invalid change notifications that are sent to your notification URL. Essas notificações de alteração inválidas podem estar tentando desencadear a lógica personalizada que você implementou.These invalid change notifications can be trying to trigger the custom logic that you implemented. Para obter uma lista completa de endereços IP usados pelo Microsoft Graph para oferecer notificações de alteração, confira pontos de extremidade adicionais para Microsoft 365.For a complete list of IP addresses used by Microsoft Graph to deliver change notifications, see additional endpoints for Microsoft 365.

Observação: Os endereços IP listados que são usados para fornecer notificações de alteração podem ser atualizados a qualquer momento sem aviso prévio.Note: The listed IP addresses that are used to deliver change notifications can be updated at any time without notice.

LatênciaLatency

A tabela a seguir lista a latência esperada entre um evento acontecendo no serviço e a entrega da notificação de alteração.The following table lists the latency to expect between an event happening in the service and the delivery of the change notification.

RecursoResource Latência médiaAverage latency Latência máximaMaximum latency
[alerta][]alert Menos de 3 minutosLess than 3 minutes 5 minutos5 minutes
callRecordcallRecord Menos de 15 minutosLess than 15 minutes 60 minutos60 minutes
chatMessagechatMessage Menos de 10 segundosLess than 10 seconds 1 minuto1 minute
contatocontact DesconhecidoUnknown DesconhecidoUnknown
conversaconversation DesconhecidoUnknown DesconhecidoUnknown
driveItemdriveItem Menos de 1 minutoLess than 1 minute 5 minutos5 minutes
[evento][]event DesconhecidoUnknown DesconhecidoUnknown
[grupo][]group Menos de 2 minutosLess than 2 minutes 15 minutos15 minutes
[lista][]list Menos de 1 minutoLess than 1 minute 5 minutos5 minutes
[mensagem][]message DesconhecidoUnknown DesconhecidoUnknown
[presença][] (pré-visualização)presence (preview) Menos de 10 segundosLess than 10 seconds 1 minuto1 minute
impressoraprinter Menos de 1 minutoLess than 1 minute 5 minutos5 minutes
printTaskDefinitionprintTaskDefinition Menos de 1 minutoLess than 1 minute 5 minutos5 minutes
todoTasktodoTask Menos de 2 minutosLess than 2 minutes 15 minutos15 minutes
[usuário][]user Menos de 2 minutosLess than 2 minutes 15 minutos15 minutes

Observação: a latência fornecida para o recurso de alerta só será aplicável depois que o próprio alerta tiver sido criado.Note: The latency provided for the alert resource is only applicable after the alert itself has been created. Não inclui o tempo necessário para uma regra criar um alerta a partir dos dados.It does not include the time it takes for a rule to create an alert from the data.

Confira tambémSee also