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

  • Artigo

Este artigo descreve as etapas para assinar eventos publicados pela API do Microsoft Graph. 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
ID do Microsoft Entra Usuário, Grupo Tipos de eventos do Microsoft Entra
Microsoft Outlook Evento (reunião do calendário), Mensagem (email), 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 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

Você cria uma assinatura da API do Microsoft Graph para permitir que os eventos dela fluam para um tópico de parceiro. O tópico de parceiro é criado automaticamente durante a criação da assinatura da API do Graph. Use esse tópico de parceiro para criar assinaturas de evento a fim de enviar os eventos a um dos manipuladores de eventos com suporte que seja mais adequado aos seus requisitos de processamento de eventos.

Importante

Se você ainda não conhece o recurso Eventos de Parceiros, confira Visão geral dos Eventos de Parceiros.

Por que devo assinar eventos de origens da API do Microsoft Graph por meio da Grade de Eventos?

Além da capacidade 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). Considere usar a API do Microsoft Graph para entregar eventos à Grade de Eventos se você tiver pelo menos um dos seguintes requisitos:

  • Você está desenvolvendo uma solução controlada por eventos que requer eventos do Microsoft Entra ID, do Outlook, do Teams e outros para reagir a alterações de recursos. Você precisa do modelo voltado para evento robusto e das funcionalidades de publicação-assinatura que a Grade de Eventos oferece. 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, webhooks ou serviços do Azure downstream, dependendo de algumas das 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ê gosta do suporte de extensibilidade que o CloudEvents fornece. Por exemplo, se você quiser rastrear eventos em sistemas em conformidade, poderá usar a extensão de Rastreamento Distribuído do CloudEvents. Saiba mais sobre outras extensões do CloudEvents.
  • Você quer usar abordagens controladas por eventos adotadas pelo setor e já comprovadas.

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

Você solicita à API do Microsoft Graph para encaminhar 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 os 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

Você deve atender 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 na seção de exemplos com instruções detalhadas, você deve ler todas as seções neste artigo, pois elas contêm informações adicionais e 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 mostram exemplos para criar uma assinatura a fim de receber eventos de todos os usuários em um locatário do Microsoft Entra ID quando eles são 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.
  • client state. 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

Seu aplicativo precisa renovar a assinatura da API do Graph antes de expirar para evitar interromper o fluxo de eventos. Para ajudar você a automatizar o processo de renovação, a API do Microsoft Graph dá suporte a eventos de notificações de ciclo de vida que o seu aplicativo pode assinar. 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 você não renovou sua assinatura da API do Graph depois que ela expirar, precisará criar uma assinatura da API do Graph. Você pode se referir ao mesmo tópico de parceiro usado em sua assinatura expirada, desde que 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, ele precisa ser pelo menos três horas posterior à 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. Confira as próximas etapas para obter mais informações.

Importante

Você precisa de código de exemplo para outra linguagem de programação ou tem dúvidas? Envie um email para ask-graph-and-grid@microsoft.com.

Próximas etapas

Siga as instruções nas seguintes duas etapas para concluir a configuração para receber eventos da API do Microsoft Graph usando a Grade de Eventos:

Outros links úteis: