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

Artigo
10/14/2024

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

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 CLI do Azure permite-lhe criar scripts e automatizar tarefas administrativas no Azure. O CLI pode ser instalado em seu computador local ou ser executado diretamente a partir do Azure Cloud Shell.

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.

# --------------
# 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}"

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.

Utilizar o RBAC
Utilizar Key Vault

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.

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

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.

 {
    "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

Crie uma conta de armazenamento.
Crie um contentor na conta de armazenamento. O nome do contentor tem de ser definido como microsoft-graph-change-notifications.
Obtenha as chaves de acesso ou cadeia de conexão da conta de armazenamento.
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://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipalsWithAppId("{appId}").GetAsync();



mgc service-principals-with-app-id get --app-id {app-id}



// 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://zcusa.951200.xyz/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();

Snippet not available


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->servicePrincipalsWithAppId('{appId}', )->get()->wait();


Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalByAppId


# 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://zcusa.951200.xyz/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.

Método 1

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://zcusa.951200.xyz/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals.PostAsync(requestBody);



mgc service-principals create --body '{\
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"\
}\
'



// 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://zcusa.951200.xyz/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);


const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
    appId: '0bf30f3b-4a52-48df-9a82-234910c4a086'
};

await client.api('/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();


Import-Module Microsoft.Graph.Applications

$params = @{
	appId = "0bf30f3b-4a52-48df-9a82-234910c4a086"
}

New-MgServicePrincipal -BodyParameter $params


# 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://zcusa.951200.xyz/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)

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"
}

Descrição geral das notificações de alteração
Confira os seguintes, inícios rápidos dos Hubs de Eventos do Azure:
- .NET Core
- Java
- Python
- JavaScript

Compartilhar via

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

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

Configurar a autenticação Hubs de Eventos do Azure

Configurar o hub de eventos

Configurar o hub de eventos

Configurar o Key Vault do Azure

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

Criar a subscrição

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

Receber notificações

Processar notificações de validação

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

Configurar o armazenamento e criar uma subscrição

Receber notificações avançadas

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

Comentários

Recursos adicionais

Compartilhar via

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

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

Configurar a autenticação Hubs de Eventos do Azure

Configurar o hub de eventos

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

Criar a subscrição

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

Receber notificações

Processar notificações de validação

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

Configurar o armazenamento e criar uma subscrição

Receber notificações avançadas

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

Conteúdo relacionado

Comentários

Recursos adicionais