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 fontes de eventos para as quais os eventos estão disponíveis por meio da Graph API. Para a maioria dos recursos, há suporte para eventos anunciando 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 fontes de eventos, consulte Recursos suportados pelas notificações de alteração da API do Microsoft Graph .

Origem de eventos da Microsoft Recursos Tipos de eventos disponíveis
Microsoft Entra ID Utilizador, Grupo Tipos de eventos do Microsoft Entra
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
Fazer Para Fazer Tarefa Eventos do Microsoft ToDo
Alertas de segurança Alert 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

Você cria 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 de parceiro é criado automaticamente para você como parte da criação da assinatura da Graph API. 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.

Por que devo me inscrever em eventos de fontes da API do Microsoft Graph por meio da Grade de Eventos?

Além da capacidade de se inscrever em eventos da API do Microsoft Graph via Event Grid, você tem outras opções através das quais você pode 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 orientada a eventos que requer eventos do Microsoft Entra ID, Outlook, Teams, etc. para reagir a alterações de recursos. Você precisa do modelo robusto controlado por eventos e dos recursos de publicação-assinatura que a Grade de Eventos fornece. Para obter uma visão geral da Grade de Eventos, consulte Conceitos de Grade de Eventos.
  • Você deseja usar a Grade de Eventos para rotear eventos para vários destinos usando uma única assinatura da API do Graph e deseja 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, dependendo de algumas das propriedades no evento. Por exemplo, talvez você queira rotear tipos de eventos, como Microsoft.Graph.UserCreated e Microsoft.Graph.UserDeleted para um aplicativo especializado que processa a integração e a desintegração dos usuários. Você também pode querer enviar Microsoft.Graph.UserUpdated eventos para outro aplicativo que sincroniza informações de contatos, por exemplo. Você pode conseguir isso usando uma única assinatura da API do Graph ao usar a Grade de Eventos como destino de notificação. Para obter mais informações, consulte filtragem de eventos e manipuladores de eventos.
  • A interoperabilidade é importante para si. Você deseja encaminhar e manipular eventos de forma padrão usando o padrão de especificação CloudEvents do Cloud Native Computing Foundation (CNCF).
  • Você gosta do suporte de extensibilidade que o CloudEvents oferece. Por exemplo, se você quiser rastrear eventos em sistemas compatíveis, use a extensão CloudEvents Distributed Tracing. Saiba mais sobre mais extensões do CloudEvents.
  • Você deseja usar abordagens comprovadas orientadas a eventos adotadas pelo setor.

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

Você solicita 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

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

  • Familiarize-se com as etapas de alto nível para se inscrever em eventos de parceiros. Conforme descrito nesse artigo, antes de criar uma assinatura da Graph API, você deve seguir as instruções em:

  • Ter um conhecimento prático das notificações da API do Microsoft Graph. Como parte do seu aprendizado, você pode usar o Graph API Explorer para criar assinaturas da 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 de usuários no Microsoft Entra ID, você deve usar o recurso do usuário . 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. Você pode obter 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 seu aplicativo sejam encontradas na seção de exemplos com instruções detalhadas, você deve ler todas as seções deste 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 ser associado à nova assinatura da API do Graph:

  • Nome do tópico do parceiro
  • Nome do grupo de recursos no qual o tópico de parceiro é criado
  • Região (localização)
  • Subscrição do Azure

Estes exemplos de código mostram como criar uma assinatura da Graph API. Eles mostram exemplos de criação de uma assinatura para 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 para as quais você deseja 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. 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>. 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 local. Por exemplo, não use o Centro-Oeste dos EUA. Utilize westcentralus em substituição. 
      az account list-locations
  • lifecycleNotificationUrl: um URI usado para definir o tópico do parceiro para o qual microsoft.graph.subscriptionReauthorizationRequiredos 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 de notificationUrl descrito anteriormente se estiver usando 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.
  • Recurso: o recurso que gera eventos que anunciam alterações de estado.
  • expirationDateTime: a hora de expiração na qual a assinatura expira e o fluxo de eventos para. Ele deve estar em conformidade com o formato especificado em Request for Change (RFC) 3339. Você deve especificar um tempo de expiração que esteja dentro do comprimento máximo de assinatura permitido por tipo de recurso.
  • estado do cliente. Esta 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, 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 aplicativo de locatário pode criar até 10 tópicos exclusivos de parceiros.

  • 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 propriedade lifecycleNotificationUrl, você deve excluir a assinatura existente e criar uma nova 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 deve renovar a assinatura da API do Graph antes que ela expire para evitar interromper o fluxo de eventos. Para ajudá-lo a automatizar o processo de renovação, a API do Microsoft Graph oferece suporte a eventos de notificações de ciclo de vida aos quais seu aplicativo pode se inscrever. Atualmente, todos os tipos de recursos da API do Microsoft Graph suportam o microsoft.graph.subscriptionReauthorizationRequired, que é enviado quando qualquer uma das seguintes condições ocorre:

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

Se você não renovou sua assinatura da Graph API depois que ela expirar, será necessário criar uma nova assinatura da Graph API. Pode consultar o mesmo tópico de parceiro que utilizou na sua subscrição expirada, desde que esta tenha expirado por 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. Nesse caso, você precisa especificar outro nome de tópico de 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

Ao receber um microsoft.graph.subscriptionReauthorizationRequired evento, 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 quando criou a assinatura da API do Graph, esse segredo do cliente foi incluído no evento. 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. Mais informações são fornecidas nas próximas amostras com a seção de instruções detalhadas.

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

      A renovação pode 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 com êxito uma assinatura.

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. É importante estar preparado para reautorizar regularmente seu endpoint para atualizar seu token de acesso. Reautorizar seu ponto de extremidade não renova sua assinatura. No entanto, a renovação da sua subscrição também reautoriza o seu ponto de extremidade.

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

Ao especificar um novo expirationDateTime, ele deve estar 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 obter exemplos sobre como reautorizar sua assinatura da Graph API usando qualquer um dos idiomas suportados, consulte Solicitação de reautorização de assinatura.

Para obter exemplos sobre como renovar e reautorizar sua assinatura da Graph API usando qualquer um dos idiomas suportados, consulte Atualizar solicitação de assinatura..

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 assinaturas da API do Graph. Para renovar uma assinatura, você pode chamar a API do Graph usando os trechos de código em Como renovar uma assinatura da API do Graph.
  • Obtenha tokens de autenticação para usá-los ao chamar a API do Microsoft Graph.

Nota

É possível criar sua assinatura da API do Graph 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
  • Exemplo de NodeJS.

Importante

Você precisa ativar o tópico de parceiro criado como parte da criação da assinatura da API do Graph. 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. Próximos passos para obter mais informações.

Importante

Você precisa de código de exemplo para outro idioma ou tem dúvidas? Por favor, envie-nos um e-mail para ask-graph-and-grid@microsoft.com.

Próximos passos

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

Outras ligações úteis: