Receber notificações de alteração através dos 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 os Hubs de Eventos do Azure.

Exemplos de cenários de débito elevado em que pode utilizar os 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 dos Hubs de Eventos do Azure.

Utilizar os Hubs de Eventos do Azure para receber uma 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 Azure Key Vault ou adicionar o serviço Deteção de Alterações do Microsoft Graph à função remetente de dados no hub de eventos.

Configurar a autenticação dos Hubs de Eventos do Azure

Usar a 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.

# --------------
# 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.

Use o portal do Azure

Configurar o hub de eventos

Nesta secção, irá:

• Crie um espaço de nomes dos Hubs 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 ligação para o hub recém-criado.

Etapas:

1. Inicie sessão no portal do Azure com privilégios para criar recursos na sua subscrição do Azure.
2. Selecione Criar um tipo de recurso>Hubs de Eventos na barra > de pesquisa, selecione a sugestão 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 do hub de eventos estiver aprovisionado, aceda à página do espaço de nomes.
6. Selecione Hubs de Eventos e + Hub de Eventos.
7. Atribua um nome ao novo hub de eventos e selecione Criar.
8. 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.
9. Atribua um nome à política, selecione Enviar e selecione Criar.
10. 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 Azure Key Vault

Para aceder ao hub de eventos de forma segura e permitir rotações de chaves, o Microsoft Graph obtém a cadeia de ligação para o hub de eventos através do Azure Key Vault.

Nesta secção, irá:

• Crie um Azure Key Vault para armazenar o segredo.
• Adicione a cadeia de ligação ao hub de eventos como segredo.
• Adicionar uma política de acesso para o Microsoft Graph acessar o segredo.

Etapas:

1. Inicie sessão no portal do Azure com privilégios para criar recursos na sua subscrição do Azure.
2. Selecione Criar um tipo de recurso>Key Vault na barra > de pesquisa, selecione a sugestão do Key Vault .
3. Na página de criação do Key Vault, selecione Criar.
4. Preencha os detalhes de criação do Key Vault e, em seguida, selecione Rever + Criar e Criar.
5. Acesse o cofre de chaves recém-criado usando o recurso Vá para da notificação.
6. Copiar o nome DNS; irá precisar dele mais adiante neste artigo.
7. Aceda a Segredos e selecione + Gerar/Importar.
8. 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.
9. Selecione Políticas de Acesso e + Adicionar Política de Acesso.
10. Para Permissões de segredo, selecione Obter, e para Selecionar Principal, selecione Controle de Alterações do Microsoft Graph. Selecione Adicionar.

Utilizar o portal do Azure (RBAC)

Configurar o hub de eventos

Nesta secção, irá:

• Crie um espaço de nomes dos Hubs 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 ligação para o hub recém-criado.

Etapas:

1. Inicie sessão no portal do Azure com privilégios para criar recursos na sua subscrição do Azure.
2. Selecione Criar um tipo de recurso>Hubs de Eventos na barra > de pesquisa, selecione a sugestão 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 do hub de eventos estiver aprovisionado, aceda à página do espaço de nomes.
6. Selecione Hubs de Eventos e + Hub de Eventos.
7. Atribua um nome ao novo hub de eventos e selecione Criar.
8. Depois de criar o hub de eventos, selecione o nome do hub de eventos e, em seguida, selecione Controlo 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çõesdafunção> Tarefa, selecione Remetente de Dados > dos Hubs de Eventos do Azure selecione Seguinte.
12. No separador Membros , selecione Atribuir acesso a Utilizador, grupo ou principal de serviço.
13. Selecione + Selecionar membros> procurar e selecione Controlo de Alterações do Microsoft Graph.
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 dos Hubs de Eventos do Azure necessários, pode agora criar a sua subscrição de notificação de alteração e começar a receber notificações de alteração através dos 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 Key Vault

Se estiver a utilizar o Key Vault, a propriedade notificationUrl terá o seguinte aspeto: EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>, com os seguintes valores:

• azurekeyvaultname - O nome que você atribuiu ao cofre de chaves quando o criou. Pode ser encontrado no nome DNS.
• secretname - O nome que você atribuiu ao segredo quando o criou. Pode ser encontrado na página Segredos. do Azure Key Vault.
• domainname - O nome do seu inquilino; por exemplo, contoso.com. Uma vez que este domínio é utilizado para aceder ao Azure Key Vault, é importante que corresponda ao domínio utilizado pela subscrição do Azure que detém o Azure Key Vault. Para obter essa informação, você pode ir para a página de visão geral do Azure Key Vault que você criou e clique na assinatura. O nome de domínio é exibido sob o campo Diretório.

Utilizar o controlo de acesso baseado em funções

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 do Hub de Eventos. Pode ser encontrado 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 encontrar-se 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 Hub de Eventos do Azure, é importante que corresponda ao domínio utilizado pela subscrição do Azure que detém o Hub de Eventos do Azure. Para obter estas informações, selecione o menu Microsoft Entra ID no portal do Azure e veja a 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 .

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 a cadeia de ligaçã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 ligaçã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 da conta de armazenamento ou a cadeia de ligação.
4. Adicione a cadeia de ligaçã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 Controlo de Alterações do Microsoft Graph estiver em falta?

O principal de serviço de Controlo de Alterações do Microsoft Graph pode 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.

HTTP

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

C#

// 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();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

CLI

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

Ir

// 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)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

Java

// 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();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

JavaScript

Snippet not available

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

PowerShell

Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalByAppId

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

Python

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.service_principals_with_app_id("{appId}").get()

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

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

HTTP

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

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

C#

// 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);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

CLI

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

Ir

// 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)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

Java

// 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);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

await client.api('/servicePrincipals')
	.post(servicePrincipal);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

PHP

<?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();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

PowerShell

Import-Module Microsoft.Graph.Applications

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

New-MgServicePrincipal -BodyParameter $params

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

Python

from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal

graph_client = GraphServiceClient(credentials, scopes)

request_body = ServicePrincipal(
	app_id = "0bf30f3b-4a52-48df-9a82-234910c4a086",
)

result = await graph_client.service_principals.post(request_body)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

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

Conteúdo relacionado

• 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