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 em serviços do Microsoft 365, incluindo Microsoft Entra ID, Teams, Outlook e OneDrive. Ao assinar esses eventos pelo Grade de Eventos do Azure, você pode construir aplicações orientadas a eventos que respondem a mudanças de recursos em tempo real.

Este artigo explica como:

  • Crie assinaturas para a API do Microsoft Graph que entreguem eventos aos tópicos de parceiro na Grade de Eventos do Azure.
  • Gerenciar ciclos de vida de assinatura com renovação automática.
  • Roteie eventos para múltiplos destinos usando as capacidades de filtragem e roteamento do 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: rotear tipos de evento específicos para aplicativos diferentes com base nas propriedades do evento.
  • Conformidade de padrões: receba eventos no formato CloudEvents para melhor interoperabilidade.
  • Confiabilidade: Lógica de repetição interna e filas de mensagens não entregues asseguram uma entrega confiável de eventos.

Fontes de evento com suporte

A tabela a seguir lista as fontes de eventos para as quais você pode obter eventos via API do Graph. Para a maioria dos recursos, a API do Graph suporta eventos que anunciam sua criação, atualização e exclusão. Para obter informações detalhadas sobre os recursos que geram eventos para fontes de eventos, consulte os recursos compatíveis com as notificações de alteração da API do Microsoft Graph.

Origem de evento da Microsoft Recursos Tipos de evento disponíveis
Microsoft Entra ID Usuário, Grupo Tipos de eventos do Microsoft Entra ID
Microsoft Outlook Evento (reunião do calendário), Mensagem (email), Contato Tipos de eventos do Microsoft Outlook
Equipes da Microsoft ChatMessage, CallRecord (reunião) Tipos de eventos do Microsoft Teams
OneDrive DriveItem Eventos do Microsoft OneDrive
Microsoft SharePoint Lista Eventos do Microsoft SharePoint
Tarefas Pendentes Tarefa do To Do Eventos do Microsoft To Do
Alertas de segurança Alerta Eventos de Alerta de Segurança da Microsoft
Impressão em nuvem Impressora, Definição de tarefa de impressão Eventos de impressão do Microsoft Cloud
Conversas da Microsoft Conversa Eventos da Conversa de 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 API do Graph cria automaticamente o tópico parceiro quando você cria a assinatura. Use esse tópico de parceiro para criar assinaturas de evento para enviar seus eventos para qualquer um dos manipuladores de eventos com suporte que melhor atendam aos seus requisitos para processar os eventos.

Importante

Se você não estiver familiarizado com o recurso Eventos do Parceiro , consulte a visão geral de Eventos do Parceiro.

Por que assinar eventos das fontes da Microsoft API do Graph através do Event Grid?

Além de assinar eventos da Microsoft API do Graph pelo Event Grid, você 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 da ID do Microsoft Entra, do Outlook ou do Teams para reagir às alterações de recursos. Você precisa do modelo robusto controlado por eventos e dos recursos de publicação e assinatura que a Grade de Eventos fornece. Para obter uma visão geral da Grade de Eventos, confira Conceitos da Grade de Eventos.
  • Você quer usar o Event Grid para rotear eventos para múltiplos destinos usando uma única assinatura da API do Graph, e quer evitar gerenciar múltiplas assinaturas da API do Graph.
  • Você precisa rotear eventos para diferentes aplicativos downstream, webhooks ou serviços do Azure com base em algumas propriedades no evento. Por exemplo, talvez você queira encaminhar tipos de evento, como Microsoft.Graph.UserUpdated e Microsoft.Graph.UserDeleted, a um aplicativo especializado que processe a integração e a remoção de usuários. Além disso, talvez você queira enviar eventos Microsoft.Graph.UserUpdated a outro aplicativo que sincronize informações de contatos, por exemplo. Você pode conseguir isso usando uma única assinatura da API do Graph ao usar o Event Grid como destino de notificação. Para obter mais informações, confira filtragem de eventos e manipuladores de eventos.
  • A interoperabilidade é importante para você. Você quer encaminhar e lidar com eventos de forma padrão usando o padrão de especificação CloudEvents da Cloud Native Computing Foundation (CNCF).
  • Você valoriza o suporte de extensibilidade que o CloudEvents fornece. Por exemplo, para rastrear eventos em sistemas em conformidade, use a extensão CloudEvents Distributed Tracing. Saiba mais sobre as extensões do CloudEvents.
  • Você utiliza abordagens comprovadas e orientadas por eventos adotadas pelo setor.

Permitir que os eventos da API do Graph fluam para o tópico de 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 (Kits de Desenvolvimento de Software) da API do Microsoft Graph e seguindo as etapas nos links para exemplos fornecidos nesta seção. Confira as Linguagens de programação com suporte para o SDK de API do Microsoft Graph para obter o suporte disponível ao SDK.

Pré-requisitos gerais

Antes de implementar sua aplicação para criar e renovar assinaturas da Microsoft API do Graph, certifique-se de atender a estes pré-requisitos gerais:

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

Importante

Embora instruções detalhadas para implementar sua aplicação estejam disponíveis na seção de exemplos com instruções detalhadas, leia todas as seções deste artigo, pois elas contêm informações mais importantes relacionadas ao encaminhamento de eventos da Microsoft API do Graph usando o Event Grid.

Como criar uma assinatura da API do Microsoft Graph

Quando você cria uma assinatura do API do Graph, o sistema cria um tópico parceiro para você. Você passa as seguintes informações no parâmetro notificationUrl para especificar o tópico parceiro a ser criado e associado à nova assinatura da API do Graph:

  • nome do tópico do parceiro
  • Nome do grupo de recursos para o tópico parceiro
  • região (localização)
  • Assinatura do Azure

Esses exemplos de código mostram como criar uma assinatura da API do Graph. Eles incluem exemplos para criar uma assinatura que receba eventos de todos os usuários em um locatário do Microsoft Entra ID quando forem criados, atualizados ou excluídos.

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 das quais você quer receber eventos. Valores válidos: Updated e Deleted (Created não é suportado pela API do Graph; confira a documentação da API do Graph 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. Ele precisa estar em conformidade com o seguinte padrão: 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 localização. Por exemplo, não use Centro-Oeste dos EUA. Use westcentralus em vez disso.

    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 aplicativo que a assinatura da API do Graph está expirando em breve. O URI segue o mesmo padrão do notificationUrl descrito anteriormente se você usar a Grade de Eventos como destino para eventos do ciclo de vida. Nesse caso, o tópico do parceiro deve ser o mesmo especificado em notificationUrl.

  • resource: o recurso que gera eventos que anunciam mudanças de estado.

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

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

Importante

  • Os nomes de tópicos de parceiro precisam ser exclusivos na mesma região do Azure. Cada combinação de locatário e ID do aplicativo pode criar até dez tópicos de parceiro exclusivos.

  • Tenha em mente alguns limites do serviço de recursos da API do Graph ao desenvolver a solução.

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

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 de expirar para evitar interromper o fluxo de eventos. Para ajudar a automatizar o processo de renovação, a Microsoft API do Graph suporta eventos de notificação do ciclo de vida aos quais os aplicativos podem se inscrever. Atualmente, todos os tipos de recursos da Microsoft API do Graph 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 assinatura da API do Graph está prestes a expirar.
  • Um administrador de locatário revogou as permissões do aplicativo para ler um recurso.

Se a assinatura da API do Graph não for renovada após expirar, crie uma nova assinatura da API do Graph. Você pode consultar o mesmo tópico de parceiro usado na assinatura expirada, desde que ela tenha expirado há menos de 30 dias. Se a assinatura da API do Graph expirou há mais de 30 dias, você não poderá reutilizar seu tópico de parceiro existente. Nesse caso, você precisa especificar o nome do tópico de outro parceiro. Como alternativa, você pode excluir o tópico de parceiro existente para criar um 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 seu aplicativo recebe um microsoft.graph.subscriptionReauthorizationRequired evento, ele deve renovar a assinatura da API do Graph:

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

  2. Verifique se o aplicativo tem um token de acesso válido para executar a próxima etapa. As próximas amostras com instruções detalhadas fornecem mais informações.

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

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

      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 o aplicativo não estiver mais autorizado a acessar o recurso. O aplicativo pode então precisar obter um novo token de acesso para reautorizar uma assinatura.

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

Quando você renova ou reautoriza sua assinatura da API do Graph, ela usa o mesmo tópico parceiro que você especificou ao criar a assinatura.

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

Para exemplos de como reautorizar sua assinatura da API do Graph usando qualquer um dos idiomas suportados, veja solicitação de reautorização de assinatura.

Para exemplos de como renovar e reautorizar sua assinatura da API do Graph usando qualquer um dos idiomas suportados, veja solicitação de atualização de assinatura.

Exemplos com instruções detalhadas

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

  • Configurar seu ambiente de desenvolvimento com instruções específicas de acordo com a linguagem de programação usada. As instruções também incluem como obter um locatário do Microsoft 365 para fins de desenvolvimento.
  • Crie uma assinatura do API do Graph. Para renovar uma assinatura, ligue para a API do Graph usando os trechos de código em Como renovar uma assinatura da API do Graph.
  • Obter tokens de autenticação para usá-los ao chamar a API do Microsoft Graph.

Observação

Você pode criar sua assinatura do API do Graph usando o Microsoft API do Graph Explorer. Você ainda deve usar os exemplos para outros aspectos importantes da solução, como autenticação e recebimento de eventos.

Os exemplos de aplicativo Web estão disponíveis para as seguintes linguagens de programação:

Importante

Você precisa ativar o tópico do parceiro criado como parte da criação da assinatura da API do Graph. Você também precisa criar uma assinatura de evento da Grade de Eventos para seu aplicativo Web para receber eventos. Para esse fim, use 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? Envie email para ask-graph-and-grid@microsoft.com.

Conteúdo relacionado

Para receber eventos da Microsoft API do Graph através do Event Grid, complete estas duas etapas:

  • Last updated on