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

  • 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 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 fontes de eventos, consulte Recursos com suporte das notificações de alteração da API do Microsoft Graph .

Importante

A capacidade da API do Microsoft Graph de enviar eventos para a Grade de Eventos do Azure está atualmente em visualização pública. Se você tiver dúvidas ou precisar de suporte, envie-nos um email para ask-graph-and-grid@microsoft.com.

Origem de evento da Microsoft Tipos de evento disponíveis
Microsoft Entra ID Tipos de eventos do Microsoft Entra
Microsoft Outlook Tipos de eventos do Microsoft Outlook
Conversas em grupo do Microsoft 365
Microsoft Teams Tipos de eventos do Microsoft Teams
Microsoft SharePoint e OneDrive
Microsoft SharePoint
Alertas de segurança
Conversas da Microsoft
Impressão Universal da Microsoft

Importante

Se você ainda não conhece o recurso Eventos de Parceiros, confira Visão geral dos 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 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 de 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 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 para um aplicativo especializado que processa a integração e Microsoft.Graph.UserDeleted a desativaçã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. 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 manipular eventos de maneira padrão usando o padrão de especificação CloudEvents do CNCF.
  • Você gosta do suporte de extensibilidade que o CloudEvents fornece. Por exemplo, se você quiser rastrear eventos em sistemas compatíveis, use a extensão CloudEvents Distributed Tracing. 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 a 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 da API do Microsoft Graph e seguindo as etapas nos links para exemplos fornecidos nesta seção. Consulte Idiomas com suporte para o SDK da API do Microsoft Graph para obter 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ê encontrará outros pré-requisitos específicos para a linguagem de programação escolhida e o ambiente de desenvolvimento usado 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 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 Graph API, 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 Graph API:

  • Nome do tópico do parceiro
  • Nome do grupo de recursos no qual o tópico de parceiro é criado
  • Região (localização)
  • Assinatura 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 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 de parceiro para o qual os eventos são enviados. Deve obedecer ao 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 local. 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 de 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 que notificationUrl descrito acima se estiver usando a Grade de Eventos como destino para eventos do ciclo de vida. Nesse caso, o tópico de parceiro deve ser o mesmo especificado em notificationUrl.
  • Recurso: O recurso que gera eventos que anunciam alterações de estado.
  • expirationDateTime: o tempo de expiração no qual a assinatura expira e o fluxo de eventos é interrompido. Ela precisa estar em conformidade com o formato especificado no RFC 3339. Você deve especificar um tempo de expiração que esteja dentro do comprimento máximo de assinatura permitido 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

  • O nome do tópico do parceiro deve ser exclusivo 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 da Graph API sem uma lifecycleNotificationUrl propriedade não recebem eventos de 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.

Observação

Se seu aplicativo usar o cabeçalho x-ms-enable-features com sua solicitação para criar uma assinatura da Graph API durante a visualização privada, você deverá removê-lo, pois não é mais necessário.

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

Renovar uma assinatura da API do Microsoft Graph

Uma assinatura da Graph API deve ser renovada pelo seu aplicativo antes de expirar para evitar a interrupção do 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 nos quais seu aplicativo pode se inscrever. Atualmente, todos os tipos de recursos da API do Microsoft Graph oferecem suporte ao 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 expirou, será necessário criar uma nova assinatura da Graph API. Você pode consultar o mesmo tópico de parceiro usado em sua assinatura expirada, desde que tenha expirado por menos de 30 dias. Se a assinatura da Graph API tiver expirado por mais de 30 dias, você não poderá reutilizar seu tópico de parceiro existente. Nesse caso, você precisará 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 Graph API.

Como renovar uma assinatura da API do Microsoft Graph

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

  1. Se você forneceu um segredo do cliente na propriedade clientState quando criou a assinatura da Graph API, esse segredo do cliente será incluído no evento. Valide se clientState do evento corresponde ao valor usado quando você criou a assinatura da Graph API.

  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 próxima seção de amostras com 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 expiração.

      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 uma assinatura com êxito.

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 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 endpoint para atualizar seu token de acesso. A reautorização do ponto de extremidade não renovará sua assinatura. No entanto, renovar sua assinatura também reautorizará seu endpoint.

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

Observação

É possível criar sua assinatura da Graph API usando o Microsoft Graph API Explorer. Você ainda deve usar os exemplos para outros aspectos importantes de 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#. Este é um exemplo atualizado que inclui como criar e renovar assinaturas da Graph API e orienta você por algumas das etapas para habilitar o fluxo de eventos.
  • Exemplo de Java
    • GraphAPIController contém código de exemplo para criar, excluir e renovar uma assinatura da Graph API. Ele deve ser usado junto com o aplicativo de amostra Java acima.
  • Exemplo de NodeJS.

Importante

Você precisa ativar o tópico de parceiro criado como parte da criação da assinatura da Graph API. Você também precisa criar uma assinatura de evento 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? Envie um email para ask-graph-and-grid@microsoft.com.

Próximas etapas

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:

Outros links úteis: