Receber eventos de alteração da API do Microsoft Graph por meio da Grade de Eventos do Azure

A API do Microsoft Graph fornece notificações de alteração para recursos nos serviços do Microsoft 365, incluindo Microsoft Entra ID, Teams, Outlook e OneDrive. Ao subscrever estes eventos através do Azure Event Grid, pode construir aplicações orientadas a eventos que respondem a alterações de recursos em tempo real.

Este artigo explica como:

  • Crie assinaturas da API do Microsoft Graph que fornecem eventos para tópicos de parceiros da Grade de Eventos do Azure.
  • Gerencie os ciclos de vida da assinatura com a renovação automática.
  • Encaminhe eventos para múltiplos destinos utilizando as capacidades de filtragem e roteamento da Event Grid.

A Grade de Eventos do Azure oferece várias vantagens em relação às assinaturas tradicionais da API do Microsoft Graph baseadas em webhook:

  • Roteamento simplificado: use uma única assinatura da API do Graph para enviar eventos para vários destinos.
  • Filtragem avançada: encaminhe tipos de eventos específicos para diferentes aplicativos com base nas propriedades do evento.
  • Conformidade com padrões: receba eventos no formato CloudEvents para melhor interoperabilidade.
  • Confiabilidade: A lógica de repetição integrada e as filas de letra morta garantem uma entrega de eventos confiável.

Fontes de eventos suportadas

A tabela seguinte lista as fontes de eventos para as quais pode obter eventos através da Graph API. Para a maioria dos recursos, a Graph API suporta eventos que anunciam a sua criação, atualização e eliminação. Para obter informações detalhadas sobre os recursos que geram eventos para origens de eventos, consulte os recursos suportados pelas notificações de alteração da API Microsoft Graph.

Fonte de eventos da Microsoft Recursos Tipos de eventos disponíveis
Microsoft Entra ID Utilizador, Grupo Tipos de evento do Microsoft Entra ID
Microsoft Outlook Evento (reunião do calendário), Mensagem (e-mail), Contato Tipos de eventos do Microsoft Outlook
Microsoft Teams ChatMessage, CallRecord (reunião) Tipos de eventos do Microsoft Teams
OneDrive DriveItem Eventos do Microsoft OneDrive
Microsoft SharePoint Lista Eventos do Microsoft SharePoint
Tarefas Tarefa a Fazer Eventos do Microsoft ToDo
Alertas de segurança Alerta Eventos do Alerta de Segurança da Microsoft
Impressão na nuvem Impressora, Definição de tarefa de impressão Eventos do Microsoft Cloud Printing
Conversas da Microsoft Conversação Eventos de conversação em grupo do Microsoft 365

Crie uma assinatura da API do Microsoft Graph para permitir que os eventos da API do Graph fluam para um tópico de parceiro. A Graph API cria automaticamente o tópico parceiro quando cria a subscrição. Use esse tópico de parceiro para criar assinaturas de eventos para enviar seus eventos para qualquer um dos manipuladores de eventos suportados que melhor atendam aos seus requisitos para processar os eventos.

Importante

Se você não estiver familiarizado com o recurso Eventos de parceiros , consulte Visão geral de eventos de parceiros.

Porque subscrever eventos das fontes Microsoft Graph API através do Event Grid?

Além de subscrever eventos Microsoft Graph API através do Event Grid, tem outras opções para receber notificações semelhantes (não eventos). Use a API do Microsoft Graph para entregar eventos à Grade de Eventos se você atender a pelo menos um destes requisitos:

  • Você está desenvolvendo uma solução orientada a eventos que usa eventos do Microsoft Entra ID, Outlook ou Teams para reagir a alterações de recursos. Você precisa do modelo robusto orientado a eventos e dos recursos de publicação-assinatura que a Grade de Eventos oferece. Para obter uma visão geral da Grade de Eventos, consulte Conceitos de Grade de Eventos.
  • Queres usar o Event Grid para encaminhar eventos para múltiplos destinos usando uma única subscrição da Graph API, e queres evitar gerir múltiplas subscrições da Graph API.
  • Você precisa rotear eventos para diferentes aplicativos downstream, webhooks ou serviços do Azure com base em algumas propriedades no evento. Por exemplo, poderá querer rotear tipos de eventos, como Microsoft.Graph.UserUpdated e Microsoft.Graph.UserDeleted, para uma aplicação especializada que processa o processo de acolhimento e encerramento de conta dos utilizadores. Você também pode querer enviar Microsoft.Graph.UserUpdated eventos para outro aplicativo que sincroniza informações de contatos, por exemplo. Pode conseguir isto usando uma única subscrição da Graph API quando utiliza o Event Grid como destino de notificação. Para obter mais informações, consulte filtragem de eventos e manipuladores de eventos.
  • A interoperabilidade é importante para si. Quer encaminhar e gerir eventos de forma padrão usando a especificação CloudEvents da Cloud Native Computing Foundation (CNCF).
  • Você valoriza o suporte de extensibilidade que o CloudEvents oferece. Por exemplo, para rastrear eventos em sistemas compatíveis, use a extensão CloudEvents Distributed Tracing. Saiba mais sobre as extensões do CloudEvents.
  • Utiliza abordagens comprovadas e orientadas por eventos, adotadas pela indústria.

Permitir que os eventos da API do Graph fluam para o tópico do seu parceiro

Solicite que a API do Microsoft Graph encaminhe eventos para um tópico de parceiro da Grade de Eventos criando uma assinatura da API do Graph usando os SDKs (Software Development Kits) da API do Microsoft Graph e seguindo as etapas nos links para exemplos fornecidos nesta seção. Consulte Idiomas suportados para o SDK da API do Microsoft Graph para obter suporte ao SDK disponível.

Pré-requisitos gerais

Antes de implementar a sua aplicação para criar e renovar subscrições da Microsoft Graph API, certifique-se de que cumpre estes pré-requisitos gerais:

  • Familiarize-se com os passos gerais para subscrever eventos parceiros. Como descrito nesse artigo, antes de criar uma subscrição da Graph API, siga as instruções em:

  • Ter um conhecimento prático das notificações da API do Microsoft Graph. Como parte da sua aprendizagem, pode usar o Graph API Explorer para criar subscrições Graph API.

  • Compreender os conceitos de Eventos de Parceiros.

  • Identifique o recurso da API do Microsoft Graph do qual você deseja receber eventos de alteração de estado do sistema. Para obter mais informações, consulte Notificações de alteração da API do Microsoft Graph. Por exemplo, para controlar alterações aos utilizadores no Microsoft Entra ID, use o recurso user. Use o grupo para controlar alterações em grupos de usuários.

  • Ter uma conta de administrador de locatário em um locatário do Microsoft 365. Obtenha um locatário de desenvolvimento gratuitamente ingressando no Microsoft 365 Developer Program.

Você encontra outros pré-requisitos específicos para a linguagem de programação de escolha e o ambiente de desenvolvimento que você usa nos links de exemplos da API do Microsoft Graph encontrados em uma próxima seção.

Importante

Embora instruções detalhadas para implementar a sua aplicação se encontrem na secção de exemplos com instruções detalhadas, leia todas as secções deste artigo, pois contêm informações mais importantes relacionadas com o encaminhamento de eventos Microsoft Graph API usando o Event Grid.

Como criar uma assinatura da API do Microsoft Graph

Quando cria uma subscrição da Graph API, o sistema cria um tópico parceiro para si. Passa a seguinte informação no parâmetro notificationUrl para especificar o tópico parceiro a criar e associar à nova subscrição da Graph API:

  • Nome do tópico do parceiro
  • Nome do grupo de recursos para o tema parceiro
  • Região (localização)
  • Subscrição do Azure

Estes exemplos de código mostram como criar uma assinatura da API do Graph. Eles incluem exemplos para criar uma subscrição a fim de receber eventos de todos os utilizadores num tenant do Microsoft Entra ID quando são criados, atualizados ou eliminados.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
    "changeType": "Updated,Deleted",
    "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "resource": "users",
    "expirationDateTime": "2026-08-31T00:00:00Z",
    "clientState": "secretClientValue"
}

  • changeType: o tipo de alterações de recurso para as quais você deseja receber eventos. Valores válidos: Updated e Deleted (Created não é suportado pela Graph API; consulte a documentação da Graph API para mais detalhes). Você pode especificar um ou mais desses valores separados por vírgulas.

  • notificationUrl: um URI usado para definir o tópico do parceiro para o qual os eventos são enviados. Deve obedecer ao seguinte modelo: EventGrid:?azuresubscriptionid=<you-azure-subscription-id>&resourcegroup=<your-resource-group-name>&partnertopic=<the-name-for-your-partner-topic>&location=<the-Azure-region-name-where-you-want-the-topic-created>. Para obter a localização (também conhecida como região nameAzure), execute o az account list-locations comando. Não use um nome de exibição de local. Por exemplo, não use "West Central US". Utilize westcentralus em substituição.

    az account list-locations

  • lifecycleNotificationUrl: um URI usado para definir o tópico parceiro para o qual microsoft.graph.subscriptionReauthorizationRequired os eventos são enviados. Esse evento sinaliza ao seu aplicativo que a assinatura da Graph API está expirando em breve. O URI segue o mesmo padrão do notificationUrl descrito anteriormente se usar o Event Grid como destino para eventos do ciclo de vida. Nesse caso, o tópico do parceiro deve ser o mesmo que o especificado em notificationUrl.

  • resource: o recurso que gera eventos que anunciam alterações de estado.

  • expirationDateTime: o tempo de expiração da subscrição expira e o fluxo de eventos para. Deve estar em conformidade com o formato especificado no Pedido de Comentários (RFC) 3339. Deve especificar um tempo de expiração que esteja dentro do comprimento máximo de subscrição permitido por tipo de recurso.

  • clientState: Use esta propriedade opcional para verificar chamadas para a sua aplicação de gestor de eventos durante a entrega de eventos. Para obter mais informações, consulte Propriedades de assinatura da API do Graph.

Importante

  • O nome do tópico do parceiro deve ser exclusivo dentro da mesma região do Azure. Cada combinação de ID de locatário-aplicativo pode criar até 10 temas de parceiros únicos.

  • Esteja atento a certos limites de serviço dos recursos da Graph API ao desenvolver sua solução.

  • As assinaturas existentes da API do Graph sem uma lifecycleNotificationUrl propriedade não recebem eventos do ciclo de vida. Para adicionar a lifecycleNotificationUrl propriedade, elimine a subscrição existente e crie uma nova subscrição que especifique a propriedade durante a criação da subscrição.

Depois de criar uma assinatura da API do Graph, você tem um tópico de parceiro criado no Azure.

Renovar uma assinatura da API do Microsoft Graph

Renove a assinatura da API do Graph antes que ela expire para evitar interromper o fluxo de eventos. Para ajudar a automatizar o processo de renovação, a Microsoft Graph API suporta eventos de notificação do ciclo de vida aos quais as aplicações podem subscrever. Atualmente, todos os tipos de recursos da Microsoft Graph API suportam o microsoft.graph.subscriptionReauthorizationRequired evento, que é enviado quando ocorre qualquer uma das seguintes condições:

  • O token de acesso está prestes a expirar.
  • A subscrição da Graph API está prestes a expirar.
  • Um administrador de locatário revogou as permissões do seu aplicativo para ler um recurso.

Se a assinatura da Graph API não for renovada depois de expirar, crie uma nova assinatura da Graph API. Pode utilizar o mesmo tópico do parceiro utilizado na subscrição expirada, desde que tenha expirado há menos de 30 dias. Se a assinatura da API do Graph expirou por mais de 30 dias, você não poderá reutilizar o tópico de parceiro existente. Neste caso, precisa de especificar o nome do tema de outro parceiro. Como alternativa, você pode excluir o tópico de parceiro existente para criar um novo tópico de parceiro com o mesmo nome durante a criação da assinatura da API do Graph.

Como renovar uma assinatura da API do Microsoft Graph

Quando a sua aplicação recebe um microsoft.graph.subscriptionReauthorizationRequired evento, deve renovar a subscrição da Graph API:

  1. Se forneceu um segredo do cliente na propriedade clientState quando criou a subscrição da Graph API, o evento inclui esse segredo do cliente. Valide se clientState do evento corresponde ao valor usado quando você criou a assinatura da API do Graph.

  2. Certifique-se de que o aplicativo tenha um token de acesso válido para dar o próximo passo. A secção seguinte exemplos com instruções detalhadas fornece mais informações.

  3. Chame uma das duas APIs a seguir. Se a chamada de API for bem-sucedida, o fluxo de notificação de alteração será retomado.

    • Chame a /reauthorize ação para reautorizar a assinatura sem estender sua data de validade.

      POST  https://graph.microsoft.com/beta/subscriptions/{id}/reauthorize

    • Execute uma ação regular de "renovação" para reautorizar e renovar a assinatura ao mesmo tempo.

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

{
   "expirationDateTime": "2026-09-30T11:00:00.0000000Z"
}

      A renovação pode falhar se a aplicação já não estiver autorizada a aceder ao recurso. A aplicação pode então precisar de obter um novo token de acesso para reautorizar uma subscrição.

Os desafios de autorização não substituem a necessidade de renovar uma assinatura antes que ela expire. Os ciclos de vida dos tokens de acesso e a expiração da assinatura não são os mesmos. O seu token de acesso pode expirar antes da sua subscrição. Esteja preparado para reautorizar regularmente o seu endpoint para atualizar o seu token de acesso. Reautorizar o seu endpoint não renova a sua assinatura. No entanto, a renovação da sua subscrição também reautoriza o seu endpoint.

Quando renova ou reautoriza a sua subscrição da Graph API, ela utiliza o mesmo tópico parceiro que especificou ao criar a subscrição.

Quando especificar um novo Tempo de Expiração, certifique-se de que é pelo menos três horas a partir da hora atual. Caso contrário, seu aplicativo poderá receber microsoft.graph.subscriptionReauthorizationRequired eventos logo após a renovação.

Para exemplos de como reautorizar a sua subscrição da Graph API utilizando qualquer uma das linguagens suportadas, consulte o pedido de reautorização de subscrição.

Para exemplos de como renovar e reautorizar a sua subscrição da Graph API utilizando qualquer uma das línguas suportadas, consulte o pedido de atualização de subscrição.

Amostras com instruções detalhadas

A documentação da API do Microsoft Graph fornece exemplos de código com instruções para:

  • Configure seu ambiente de desenvolvimento com instruções específicas de acordo com a linguagem que você usa. As instruções também incluem como obter um locatário do Microsoft 365 para fins de desenvolvimento.
  • Crie uma subscrição Graph API. Para renovar uma subscrição, ligue à Graph API usando os excertos de código em Como renovar uma subscrição da Graph API.
  • Obtenha tokens de autenticação para usá-los ao chamar a API do Microsoft Graph.

Nota

Pode criar a sua subscrição Graph API usando o Microsoft Graph API Explorer. Você ainda deve usar os exemplos para outros aspetos importantes da sua solução, como autenticação e recebimento de eventos.

Exemplos de aplicativos Web estão disponíveis para os seguintes idiomas:

  • Exemplo de C#. É um exemplo atualizado que inclui como criar e renovar assinaturas da API do Graph e orienta você por algumas das etapas para habilitar o fluxo de eventos.
  • Exemplo de Java
  • Node.js amostra.

Importante

Você precisa ativar o seu tópico de parceiro que foi criado como parte da criação da sua assinatura na Graph API. Você também precisa criar uma assinatura de eventos da Grade de Eventos para seu aplicativo Web para receber eventos. Para esse fim, você usa a URL configurada em seu aplicativo Web para receber eventos como um ponto de extremidade de webhook em sua assinatura de evento.

Importante

Precisa de código de exemplo para outro idioma ou tem dúvidas? E-mail ask-graph-and-grid@microsoft.com.

Conteúdo relacionado

Para receber eventos Microsoft Graph API através do Event Grid, complete estes dois passos:

  • Last updated on