Receber notificações de alteração através de Hubs de Eventos do Azure
Artigo
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.
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
Inicie sessão no portal do Azure com privilégios para criar recursos na sua subscrição do Azure.
Selecione Criar um recurso, escreva Hubs de Eventos na barra de pesquisa e, em seguida, selecione a sugestão dos Hubs de Eventos .
Na página criação dos Hubs de Eventos, selecione Criar.
Preencha os detalhes de criação do espaço de nomes dos Hubs de Eventos e, em seguida, selecione Criar.
Quando o espaço de nomes dos Hubs de Eventos estiver aprovisionado, aceda à página do espaço de nomes.
Selecione Hubs de Eventos e, em seguida, + Hub de Eventos.
Atribua um nome ao novo hub de eventos e selecione Criar.
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.
Selecione Atribuições de Funções.
Selecione + Adicionar e selecione Adicionar Atribuição de Função.
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.
No separador Membros , selecione Atribuir acesso a Utilizador, grupo ou principal de serviço.
Selecione + Selecionar membros e, em seguida, procure e selecione Microsoft Graph Controle de Alterações.
Selecione Rever + atribuir para concluir o processo.
Esta secção demonstra como configurar Hubs de Eventos do Azure autenticação com assinaturas de acesso partilhado (SAS) através da CLI do Azure.
A autenticação dos Hubs de Eventos através de assinaturas de acesso partilhado (SAS) será preterida no futuro. Recomendamos que utilize Microsoft Entra ID controlo de acesso baseado em funções (RBAC). Siga a documentação de orientação para migrar para o RBAC.
# --------------
# TODO: update the following values
#sets the name of the resource group
resourcegroup=rg-graphevents-dev
#sets the location of the resources
location='uk south'
#sets the name of the Azure Event Hubs namespace
evhamespacename=evh-graphevents-dev
#sets the name of the hub under the namespace
evhhubname=graphevents
#sets the name of the access policy to the hub
evhpolicyname=grapheventspolicy
#sets the name of the Azure KeyVault
keyvaultname=kv-graphevents
#sets the name of the secret in Azure KeyVault that will contain the connection string to the hub
keyvaultsecretname=grapheventsconnectionstring
# --------------
az group create --location $location --name $resourcegroup
az eventhubs namespace create --name $evhamespacename --resource-group $resourcegroup --sku Basic --location $location
az eventhubs eventhub create --name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --partition-count 2 --message-retention 1
az eventhubs eventhub authorization-rule create --name $evhpolicyname --eventhub-name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --rights Send
evhprimaryconnectionstring=`az eventhubs eventhub authorization-rule keys list --name $evhpolicyname --eventhub-name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --query "primaryConnectionString" --output tsv`
az keyvault create --name $keyvaultname --resource-group $resourcegroup --location $location --enable-soft-delete true --sku standard --retention-days 90
az keyvault secret set --name $keyvaultsecretname --value $evhprimaryconnectionstring --vault-name $keyvaultname --output none
graphspn=`az ad sp list --display-name 'Microsoft Graph Change Tracking' --query "[].appId" --output tsv`
az keyvault set-policy --name $keyvaultname --resource-group $resourcegroup --secret-permissions get --spn $graphspn --output none
keyvaulturi=`az keyvault show --name $keyvaultname --resource-group $resourcegroup --query "properties.vaultUri" --output tsv`
domainname=`az ad signed-in-user show --query 'userPrincipalName' | cut -d '@' -f 2 | sed 's/\"//'`
notificationUrl="EventHub:${keyvaulturi}secrets/${keyvaultsecretname}?tenantId=${domainname}"
echo "Notification Url:\n${notificationUrl}"
Nota: O script fornecido aqui é compatível com shells baseadas em Linux, Windows WSL e Azure Cloud Shell. Necessita de algumas atualizações para ser executada em shells do Windows.
Esta secção demonstra como configurar Hubs de Eventos do Azure autenticação com assinaturas de acesso partilhado (SAS) através do portal do Azure.
Importante
A autenticação dos Hubs de Eventos através de assinaturas de acesso partilhado (SAS) será preterida no futuro. Recomendamos que utilize Microsoft Entra ID controlo de acesso baseado em funções (RBAC). Siga a documentação de orientação para migrar para o RBAC.
Configurar o hub de eventos
Nesta secção, irá:
Crie um espaço de nomes do Hub de Eventos.
Adicione um hub a esse espaço de nomes para reencaminhar e entregar notificações.
Adicione uma política de acesso partilhado que lhe permita obter uma cadeia de conexão ao hub recém-criado.
Etapas:
Inicie sessão no portal do Azure com privilégios para criar recursos na sua subscrição do Azure.
Selecione Criar um recurso, escreva Hubs de Eventos na barra de pesquisa e, em seguida, selecione a sugestão dos Hubs de Eventos .
Na página criação dos Hubs de Eventos, selecione Criar.
Preencha os detalhes de criação do espaço de nomes dos Hubs de Eventos e, em seguida, selecione Criar.
Quando o espaço de nomes dos Hubs de Eventos estiver aprovisionado, aceda à página do espaço de nomes.
Selecione Hubs de Eventos e, em seguida, + Hub de Eventos.
Atribua um nome ao novo hub de eventos e selecione Criar.
Depois de criar o hub de eventos, selecione o nome do hub de eventos e, em seguida, selecione Políticas de acesso partilhado e + Adicionar para adicionar uma nova política.
Atribua um nome à política, marcar Enviar e selecione Criar.
Após a criação da política, selecione o nome da política para abrir o painel de detalhes e, em seguida, copie o valor Chave primária da cadeia de ligação . Registar o valor; precisa dele para o próximo passo.
Configurar o Key Vault do Azure
Para aceder ao hub de eventos de forma segura e permitir rotações de chaves, o Microsoft Graph obtém o cadeia de conexão para o hub de eventos através do Azure Key Vault.
Nesta secção, irá:
Crie um Key Vault do Azure para armazenar o segredo.
Adicione o cadeia de conexão ao hub de eventos como segredo.
Adicionar uma política de acesso para o Microsoft Graph acessar o segredo.
Etapas:
Inicie sessão no portal do Azure com privilégios para criar recursos na sua subscrição do Azure.
Selecione Criar um recurso, escreva Key Vault na barra de pesquisa e, em seguida, selecione a sugestão de Key Vault.
Na página de criação do Key Vault, selecione Criar.
Preencha os detalhes de criação do Key Vault e, em seguida, selecione Rever + Criar e Criar.
Acesse o cofre de chaves recém-criado usando o recurso Vá para da notificação.
Copiar o nome DNS; irá precisar dele mais adiante neste artigo.
Aceda a Segredos e selecione + Gerar/Importar.
Atribua um nome ao segredo e mantenha o nome para mais tarde; irá precisar dele mais adiante neste artigo. Para o valor, cole a cadeia de conexão que você gerou na etapa Hubs de Eventos. Selecione Criar.
Selecione Políticas de Acesso e, em seguida, + Adicionar Política de Acesso.
Para Permissões de segredo, selecione Obter, e para Selecionar Principal, selecione Controle de Alterações do Microsoft Graph. Selecione Adicionar.
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.
<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.
Se estiver a utilizar Key Vault, a propriedade notificationUrl tem o seguinte aspeto: EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>, com os seguintes valores:
<azurekeyvaultname> - O nome que deu ao cofre de chaves durante a criação. Pode encontrá-la no nome DNS.
<secretname> - O nome que deu ao segredo durante a criação. Pode encontrá-la na página Segredos Key Vault do Azure.
<domainname> - O nome do seu inquilino; por exemplo, contoso.com. Uma vez que este domínio é utilizado para aceder ao Key Vault do Azure, é importante que corresponda ao domínio utilizado pela subscrição do Azure que detém a Key Vault do Azure. Para obter estas informações, pode aceder à página de descrição geral do Azure Key Vault criou e selecionar a subscrição. O nome de domínio é exibido sob o campo Diretó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.
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.
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.
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.
Adicione o cadeia de conexão ao cofre de chaves e atribua-lhe um nome. Este valor é o nome do segredo.
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')
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipalsWithAppId("{appId}").GetAsync();
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
//other-imports
)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
appId := "{appId}"
servicePrincipals, err := graphClient.ServicePrincipalsWithAppId(&appId).Get(context.Background(), nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal result = graphClient.servicePrincipalsWithAppId("{appId}").get();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
result = await graph_client.service_principals_with_app_id("{appId}").get()
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.
POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json
{
"appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ServicePrincipal
{
AppId = "0bf30f3b-4a52-48df-9a82-234910c4a086",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewServicePrincipal()
appId := "0bf30f3b-4a52-48df-9a82-234910c4a086"
requestBody.SetAppId(&appId)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setAppId("0bf30f3b-4a52-48df-9a82-234910c4a086");
ServicePrincipal result = graphClient.servicePrincipals().post(servicePrincipal);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ServicePrincipal();
$requestBody->setAppId('0bf30f3b-4a52-48df-9a82-234910c4a086');
$result = $graphServiceClient->servicePrincipals()->post($requestBody)->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ServicePrincipal(
app_id = "0bf30f3b-4a52-48df-9a82-234910c4a086",
)
result = await graph_client.service_principals.post(request_body)