Compartilhar via

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 por meio da Grade de Eventos do Azure, você cria aplicativos controlados por eventos que respondem a alterações 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.
  • Rotear eventos para vários destinos usando os recursos de filtragem e roteamento da Grade de Eventos.

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 origens de evento para as quais há eventos disponíveis por meio da API do Graph. Para a maioria dos recursos, há suporte para eventos que anunciam sua criação, atualização e exclusão. Para obter informações detalhadas sobre os recursos para os quais os eventos são gerados para origens de evento, confira 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
To Do 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. O tópico do parceiro é criado automaticamente ao criar a assinatura da API do Graph. 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 devo assinar eventos de origens da API do Microsoft Graph por meio da Grade de Eventos?

Além de assinar eventos da API do Microsoft Graph por meio da Grade de Eventos, 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 a Grade de Eventos para encaminhar eventos a vários destinos usando uma só assinatura da API do Graph e evitar o gerenciamento de várias 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.UserCreated 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. Isso pode ser feito usando uma só assinatura da API do Graph ao usar a Grade de Eventos como destino de notificação. Para obter mais informações, confira filtragem de eventos e manipuladores de eventos.
  • A interoperabilidade é importante para você. Você deseja encaminhar e lidar com eventos de maneira padrão usando o padrão de especificação CloudEvents do CNCF (Cloud Native Computing Foundation).
  • 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ê usa abordagens comprovadas orientadas a 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

Atenda a estes pré-requisitos gerais antes de implementar seu aplicativo para criar e renovar assinaturas da API do Microsoft Graph:

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 as instruções detalhadas para implementar seu aplicativo sejam encontradas nos exemplos com a seção de instruções detalhadas , você deve ler todas as seções neste artigo, pois elas contêm informações mais importantes relacionadas ao encaminhamento de eventos da API do Microsoft Graph usando a Grade de Eventos.

Como criar uma assinatura da API do Microsoft Graph

Quando você cria uma assinatura da API do Graph, um tópico de parceiro é criado para você. Você passa as seguintes informações no parâmetro notificationUrl para especificar qual tópico de parceiro criar e associar à nova assinatura da API do Graph:

  • nome do tópico do parceiro
  • nome do grupo de recursos no qual o tópico do parceiro é criado
  • 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,Created",
    "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": "2024-03-31T00:00:00Z",
    "clientState": "secretClientValue"
}
  • changeType: o tipo de alterações de recurso das quais você quer receber eventos. Valores válidos: Updated, Deleted e Created. 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>. O local (também conhecido como região do Azure) name pode ser obtido executando o comando az account list-locations . 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 do parceiro para o qual os microsoft.graph.subscriptionReauthorizationRequiredeventos são enviados. Esse evento sinaliza ao aplicativo que a assinatura da API do Graph está expirando em breve. O URI seguirá o mesmo padrão que o notificationUrl descrito anteriormente se estiver usando a Grade de Eventos como destino para eventos de 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 alterações de estado.
  • expirationDateTime: a hora de expiração em que a assinatura expira, interrompendo o fluxo de eventos. Isso deve estar em conformidade com o formato especificado em Solicitação de alteração (RFC) 3339. Você precisa especificar uma hora de expiração dentro da duração máxima da assinatura permitida por tipo de recurso.
  • estado do cliente. Essa propriedade é opcional. Ele é usado para verificação de chamadas para seu aplicativo manipulador de eventos durante a entrega de eventos. 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 propriedade lifecycleNotificationUrl, você deve excluir a assinatura existente e criar uma assinatura especificando 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 API do Microsoft Graph dá suporte a eventos de notificações de ciclo de vida aos quais os aplicativos podem se inscrever. Atualmente, todos os tipos de recursos da API do Microsoft Graph dão suporte ao microsoft.graph.subscriptionReauthorizationRequired, 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. Consulte o mesmo tópico de parceiro utilizado na assinatura expirada, desde que a assinatura 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 outro nome de tópico do 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

Ao receber um evento microsoft.graph.subscriptionReauthorizationRequired, seu aplicativo deve renovar a assinatura da API do Graph executando estas ações:

  1. Se você forneceu um segredo do cliente na propriedade clientState ao criar a assinatura da API do Graph, esse segredo do cliente será incluído no evento. 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. Mais informações são fornecidas na seção subsequente, amostras com instruções detalhadas.

  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": "2024-04-30T11:00:00.0000000Z"
}

      A renovação poderá falhar se o aplicativo não estiver mais autorizado a acessar o recurso. Em seguida, pode ser necessário que o aplicativo obtenha um novo token de acesso para reautorizar uma assinatura com êxito.

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. É importante estar preparado para reautorizar regularmente seu ponto de extremidade para atualizar o 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.

Ao renovar e/ou reautorizar sua assinatura da API do Graph, o mesmo tópico de parceiro especificado quando a assinatura foi criada é usado.

Ao especificar um novo expirationDateTime, verifique se ele está a pelo menos três horas da hora atual. Caso contrário, seu aplicativo poderá receber eventos microsoft.graph.subscriptionReauthorizationRequired logo após a renovação.

Para obter exemplos sobre como reautorizar sua assinatura da API do Graph usando qualquer um dos idiomas com suporte, consulte a solicitação de reautorização da assinatura.

Para obter exemplos sobre como renovar e reautorizar sua assinatura da API do Graph usando qualquer um dos idiomas com suporte, consulte atualizar a solicitaçã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.
  • Criar uma assinatura da API do Graph. Para renovar uma assinatura, você pode chamar a API do Graph usando os snippets de código em Como renovar uma assinaturada API do Graph.
  • Obter tokens de autenticação para usá-los ao chamar a API do Microsoft Graph.

Observação

É possível criar sua assinatura da API do Graph usando o Gerenciador de API do Microsoft Graph. 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? Email ask-graph-and-grid@microsoft.com.

Conteúdo relacionado

Siga estas duas etapas para configurar o recebimento de eventos da API do Microsoft Graph usando a Grade de Eventos:

  • Last updated on