Compartilhar via


Receber notificações de alteração através de Hubs de Eventos do Azure

Os webhooks não são adequados para receber notificações de alteração em cenários de débito elevado ou quando o recetor não consegue expor um URL de notificação publicamente disponível. Como alternativa, pode utilizar Hubs de Eventos do Azure.

Exemplos de cenários de débito elevado em que pode utilizar Hubs de Eventos do Azure incluem aplicações que subscrevem um grande conjunto de recursos, aplicações que subscrevem recursos que mudam frequentemente e aplicações multi-inquilino que subscrevem recursos num grande conjunto de organizações.

O artigo orienta-o ao longo do processo de gestão da sua subscrição do Microsoft Graph e como receber notificações de alteração através de Hubs de Eventos do Azure.

Importante

A autenticação dos Hubs de Eventos através de assinaturas de acesso partilhado (SAS) será preterida no futuro. Recomendamos que a autenticação dos Hubs de Eventos utilize Microsoft Entra ID controlo de acesso baseado em funções (RBAC).

Utilizar Hubs de Eventos do Azure para receber a notificação de alteração

Os Hubs de Eventos do Azure é um serviço popular de inclusão e distribuição de eventos em tempo real, compilado para ser dimensionável. Usar os Hubs de Eventos do Azure para receber notificações de alteração difere do webhooks em algumas maneiras, incluindo:

  • Você não depende de URLs com notificações publicamente expostas. O SDK dos Hubs de Eventos reencaminha as notificações para a sua aplicação.
  • Não é necessário responder à validação da URL de notificação. Você pode ignorar a mensagem de validação recebida.
  • Tem de aprovisionar um hub de eventos.
  • Tem de aprovisionar um Key Vault do Azure ou adicionar o serviço de Controle de Alterações do Microsoft Graph à função Remetente de Dados no seu hub de eventos.

Configurar a autenticação Hubs de Eventos do Azure

Hubs de Eventos do Azure suporta a autenticação através de assinaturas de acesso partilhado (SAS) ou Microsoft Entra ID controlo de acesso baseado em funções (RBAC). Para obter mais informações, veja Autorizar o acesso ao Hubs de Eventos do Azure.

Esta secção demonstra como configurar a autenticação Hubs de Eventos do Azure com Microsoft Entra ID controlo de acesso baseado em funções (RBAC) no portal do Azure.

Configurar o hub de eventos
  1. Inicie sessão no portal do Azure com privilégios para criar recursos na sua subscrição do Azure.
  2. Selecione Criar um recurso, escreva Hubs de Eventos na barra de pesquisa e, em seguida, selecione a sugestão dos Hubs de Eventos .
  3. Na página criação dos Hubs de Eventos, selecione Criar.
  4. Preencha os detalhes de criação do espaço de nomes dos Hubs de Eventos e, em seguida, selecione Criar.
  5. Quando o espaço de nomes dos Hubs de Eventos estiver aprovisionado, aceda à página do espaço de nomes.
  6. Selecione Hubs de Eventos e, em seguida, + Hub de Eventos.
  7. Atribua um nome ao novo hub de eventos e selecione Criar.
  8. Depois de criar o hub de eventos, aceda ao espaço de nomes dos Hubs de Eventos e, em seguida, selecione Controle de Acesso (IAM) na barra lateral.
  9. Selecione Atribuições de Funções.
  10. Selecione + Adicionar e selecione Adicionar Atribuição de Função.
  11. Em Função, aceda a Funções de função de trabalho, selecione Hubs de Eventos do Azure Remetente de Dados e, em seguida, selecione Seguinte.
  12. No separador Membros , selecione Atribuir acesso a Utilizador, grupo ou principal de serviço.
  13. Selecione + Selecionar membros e, em seguida, procure e selecione Microsoft Graph Controle de Alterações.
  14. Selecione Rever + atribuir para concluir o processo.

Criar a subscrição e receber notificações

Depois de criar os serviços do Azure KeyVault e Hubs de Eventos do Azure necessários, pode agora criar a subscrição de notificação de alteração e começar a receber notificações de alteração através de Hubs de Eventos do Azure.

Criar a subscrição

A criação de uma subscrição para receber notificações de alteração com os Hubs de Eventos é quase idêntica à criação da subscrição do webhook, mas com alterações importantes na propriedade notificationUrl . Primeiro, reveja os passos de criação da subscrição do webhook antes de continuar.

Na criação da subscrição, o notificationUrl tem de apontar para a localização dos Hubs de Eventos.

Se estiver a utilizar o controlo de acesso baseado em funções, a propriedade notificationUrl terá o seguinte aspeto:

EventHub:https://<eventhubnamespace>.servicebus.windows.net/eventhubname/<eventhubname>?tenantId=<domainname>

  • <eventhubnamespace> é o nome que atribui ao espaço de nomes dos Hubs de Eventos. Pode encontrá-la na página Descrição Geral dos Hubs de Eventos em Nome do anfitrião.
  • <eventhubname> é o nome que dá ao hub de eventos. Pode encontrá-lo nos Hubs de Eventos –> Descrição Geral –> Hubs de Eventos.
  • <domainname> é o nome do seu inquilino; por exemplo, contoso.com. Uma vez que este domínio é utilizado para aceder ao Hubs de Eventos do Azure, é importante que corresponda ao domínio utilizado pela subscrição do Azure que detém o Hubs de Eventos do Azure. Para obter estas informações, selecione o menu Microsoft Entra ID no portal do Azure e marcar página Descrição geral. O nome de domínio é apresentado no domínio Primário.

Observação

Não são permitidas subscrições duplicadas. Quando um pedido de subscrição contém os mesmos valores para changeType e recurso que uma subscrição existente contém, o pedido falha com um código 409 Conflictde erro HTTP e a mensagem Subscription Id <> already exists for the requested combinationde erro .

Migrar uma autenticação do hub de eventos para Microsoft Entra ID RBAC

A autenticação dos Hubs de Eventos através de assinaturas de acesso partilhado (SAS) será preterida no futuro. Recomendamos que a autenticação dos Hubs de Eventos utilize Microsoft Entra ID controlo de acesso baseado em funções (RBAC).

Esta secção orienta-o ao longo de como migrar os Hubs de Eventos existentes com a autenticação SAS para Microsoft Entra ID autenticação RBAC. Utilize o mesmo espaço de nomes do hub de eventos que utilizou com a autenticação SAS, seja através da CLI do Azure ou do portal do Azure.

  1. No mesmo espaço de nomes do hub de eventos que está a utilizar para a sua subscrição existente, crie um novo hub de eventos.
  2. Crie uma nova subscrição com os mesmos detalhes que a existente, exceto com o nome do novo hub de eventos do passo anterior no URL. Para obter mais informações, veja Criar a subscrição: Utilizar o RBAC.

Receberá notificações no novo hub de eventos. Pode validar se o tráfego é semelhante ao da subscrição antiga ao inspecionar o gráfico Mensagens do hub de eventos. Valide também se existem erros ou falhas na receção de notificações.

Depois de confirmar que está a receber notificações e que o novo hub de eventos funciona corretamente, pode eliminar a subscrição antiga, o hub de eventos antigo e a autenticação baseada em SAS e começar a utilizar a nova.

Receber notificações

As notificações de alteração são agora entregues na sua aplicação pelos Hubs de Eventos. Para detalhes, confira Recebendo eventos na documentação Hubs de Eventos.

Antes de poder receber as notificações na sua aplicação, tem de criar outra política de acesso partilhado com uma permissão "Escutar" e obter o cadeia de conexão, semelhante aos passos listados em Configurar o hub de eventos.

Dica

Crie uma política separada para a aplicação que escuta mensagens dos Hubs de Eventos em vez de reutilizar a mesma cadeia de conexão que definiu no Azure KeyVault. Esta separação segue o princípio do menor privilégio ao garantir que cada componente da solução tem apenas as permissões de que precisa.

Processar notificações de validação

A sua aplicação recebe notificações de validação sempre que cria uma nova subscrição. Você deve ignorar essas notificações. O exemplo a seguir representa o corpo de uma mensagem de validação.

 {
    "value":[
        {
            "subscriptionId":"NA",
            "subscriptionExpirationDateTime":"NA",
            "clientState":"NA",
            "changeType":"Validation: Testing client application reachability for subscription Request-Id: 522a8e7e-096a-494c-aaf1-ac0dcfca45b7",
            "resource":"NA",
            "resourceData":{
                "@odata.type":"NA",
                "@odata.id":"NA",
                "id":"NA"
            }
        }
    ]
}

Subscrições para notificações avançadas com payloads grandes

O tamanho máximo da mensagem para os Hubs de Eventos é de 1 MB. Quando utiliza notificações avançadas, poderá esperar notificações que excedam este limite. Para receber notificações superiores a 1 MB através dos Hubs de Eventos, também tem de adicionar uma conta de armazenamento de blobs ao pedido de subscrição.

Configurar o armazenamento e criar uma subscrição

  1. Crie uma conta de armazenamento.
  2. Crie um contentor na conta de armazenamento. O nome do contentor tem de ser definido como microsoft-graph-change-notifications.
  3. Obtenha as chaves de acesso ou cadeia de conexão da conta de armazenamento.
  4. Adicione o cadeia de conexão ao cofre de chaves e atribua-lhe um nome. Este valor é o nome do segredo.
  5. Crie ou recrie a sua subscrição, incluindo agora a propriedade blobStoreUrl na seguinte sintaxe: blobStoreUrl: "https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>"

Receber notificações avançadas

Quando os Hubs de Eventos recebem um payload de notificação superior a 1 MB, a notificação não contém as propriedades resource, resourceData e encryptedContent incluídas em notificações avançadas. Em vez disso, a notificação contém uma propriedade AdditionalPayloadStorageId com um ID que aponta para o blob na sua conta de armazenamento onde estas propriedades estão armazenadas.

E se a aplicação de Controle de Alterações do Microsoft Graph estiver em falta?

O principal de serviço do Microsoft Graph Controle de Alterações poderá estar em falta no seu inquilino, dependendo de quando o inquilino foi criado e das operações administrativas. O appId exclusivo global do principal de serviço é 0bf30f3b-4a52-48df-9a82-234910c4a086 e pode executar a seguinte consulta para confirmar se existe no inquilino.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='0bf30f3b-4a52-48df-9a82-234910c4a086')

Se o principal de serviço não existir, crie-o da seguinte forma. Tem de conceder à aplicação de chamada a permissão Application.ReadWrite.All para executar esta operação.

Método 1

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"
}

Método 2

POST https://graph.microsoft.com/v1.0/servicePrincipals(appId='0bf30f3b-4a52-48df-9a82-234910c4a086')
Content-type: application/json
Prefer: create-if-missing

{
    "displayName": "Microsoft Graph Change Tracking"
}