Receber notificações de alteração por meio de Hubs de Eventos do Azure

Os webhooks não são adequados para receber notificações de alteração em cenários de alta taxa de transferência ou quando o receptor não pode expor uma URL de notificação disponível publicamente. Como alternativa, você pode usar Hubs de Eventos do Azure.

Exemplos de cenários de alta taxa de transferência em que você pode usar Hubs de Eventos do Azure incluem aplicativos que assinam um grande conjunto de recursos, aplicativos que assinam recursos que mudam com frequência e aplicativos multilocatários que assinam recursos em um grande conjunto de organizações.

O artigo orienta você durante o processo de gerenciamento de sua assinatura do Microsoft Graph e como receber notificações de alteração por meio de Hubs de Eventos do Azure.

Usando 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 retransmite as notificações para seu aplicativo.
• Não é necessário responder à validação da URL de notificação. Você pode ignorar a mensagem de validação recebida.
• Você precisa provisionar um hub de eventos.
• Você precisa provisionar um Key Vault do Azure ou adicionar o serviço de Controle de Alterações do Microsoft Graph à função de Remetente de Dados no Hub de Eventos.

Configurar a autenticação Hubs de Eventos do Azure

Usar a CLI do Azure

A CLI do Azure permite que você faça script e automatize 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 baseados em Linux, Windows WSL e Cloud Shell do Azure. Ele requer algumas atualizações para serem executadas em shells do Windows.

Use o portal do Azure

Configurar o hub de eventos

Nesta seção, você:

• Create um namespace dos Hubs de Eventos.
• Adicione um hub a esse namespace para retransmitir e entregar notificações.
• Adicione uma política de acesso compartilhado que permita obter uma cadeia de conexão ao hub recém-criado.

Etapas:

1. Entre no portal do Azure com privilégios para criar recursos em sua assinatura do Azure.
2. Selecione Create um tipo de recurso>Hubs de Eventos na barra de > pesquisa selecione a sugestão Hubs de Eventos.
3. Na página de criação dos Hubs de Eventos, selecione Create.
4. Preencha os detalhes de criação do namespace dos Hubs de Eventos e selecione Create.
5. Quando o namespace do hub de eventos for provisionado, acesse a página para o namespace.
6. Selecione Hubs de Eventos e + Hub de Eventos.
7. Dê um nome ao novo hub de eventos e selecione Create.
8. Depois que o hub de eventos for criado, selecione o nome do hub de eventos e selecione Políticas de acesso compartilhado e + Adicionar para adicionar uma nova política.
9. Dê um nome à política, marcar Enviar e selecione Create.
10. Depois que a política for criada, selecione o nome da política para abrir o painel de detalhes e copie o valor da chave primária de cadeia de caracteres de conexão . Registre o valor; você precisa dela para a próxima etapa.

Configurar o Key Vault do Azure

Para acessar o hub de eventos com segurança e permitir rotações de chaves, o Microsoft Graph obtém o cadeia de conexão para o hub de eventos por meio do Azure Key Vault.

Nesta seção, você:

• Create um Key Vault do Azure para armazenar o segredo.
• Adicione o cadeia de conexão ao hub de eventos como um segredo.
• Adicionar uma política de acesso para o Microsoft Graph acessar o segredo.

Etapas:

1. Entre no portal do Azure com privilégios para criar recursos em sua assinatura do Azure.
2. Selecione Create umtipo de recurso > Key Vault na barra de > pesquisa selecione a sugestão Key Vault.
3. Na página de criação Key Vault, selecione Create.
4. Preencha os detalhes de criação Key Vault e selecione Examinar + Create e Create.
5. Acesse o cofre de chaves recém-criado usando o recurso Vá para da notificação.
6. Copie o nome DNS; você precisa dele mais tarde neste artigo.
7. Vá para Segredos e selecione + Gerar/Importar.
8. Dê um nome ao segredo e mantenha o nome para depois; você precisa dele mais tarde 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.

Usar o RBAC (portal do Azure)

Configurar o hub de eventos

Nesta seção, você:

• Create um namespace dos Hubs de Eventos.
• Adicione um hub a esse namespace para retransmitir e entregar notificações.
• Adicione uma política de acesso compartilhado que permita obter uma cadeia de conexão ao hub recém-criado.

Etapas:

1. Entre no portal do Azure com privilégios para criar recursos em sua assinatura do Azure.
2. Selecione Create um tipo de recurso>Hubs de Eventos na barra de > pesquisa selecione a sugestão Hubs de Eventos.
3. Na página de criação dos Hubs de Eventos, selecione Create.
4. Preencha os detalhes de criação do namespace dos Hubs de Eventos e selecione Create.
5. Quando o namespace do hub de eventos for provisionado, acesse a página para o namespace.
6. Selecione Hubs de Eventos e + Hub de Eventos.
7. Dê um nome ao novo hub de eventos e selecione Create.
8. Depois que o hub de eventos for criado, selecione o nome do hub de eventos e selecione Controle de Acesso (IAM) na barra lateral.
9. Selecione Atribuições de Função.
10. Selecione + Adicionar e selecione Adicionar Atribuição de Função.
11. > EmFunções> de função De trabalho, selecione Hubs de Eventos do Azure Remetente> de Dados selecione Avançar.
12. Na guia Membros , selecione Atribuir acesso a Usuário, grupo ou entidade de serviço.
13. Selecione + Selecionar membros> pesquise e selecione Microsoft Graph Controle de Alterações.
14. Selecione Examinar + atribuir para concluir o processo.

Create a assinatura e receber notificações

Depois de criar os serviços necessários do Azure KeyVault e Hubs de Eventos do Azure, agora você pode criar sua assinatura de notificação de alterações e começar a receber notificações de alteração por meio de Hubs de Eventos do Azure.

Create a assinatura

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

Na criação da assinatura, o notificationUrl deve apontar para o local dos Hubs de Eventos.

Usando Key Vault

Se você estiver usando Key Vault, a propriedade notificationUrl será semelhante a esta: 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 locatário; por exemplo, contoso.com. Como esse domínio é usado para acessar o Azure Key Vault, é importante que ele corresponda ao domínio usado pela assinatura do Azure que contém o Key Vault do Azure. 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.

Usando o controle de acesso baseado em função

Se você estiver usando o controle de acesso baseado em função, a propriedade notificationUrl será semelhante a esta:

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

• eventhubnamespace é o nome que você dá ao namespace do Hub de Eventos. Pode ser encontrado na página Visão geral dos Hubs de Eventos em Nome do Host.
• eventhubname é o nome que você dá ao Hub de Eventos. Pode ser encontrado nos Hubs de Eventos –> Visão geral –> Hubs de Eventos.
• domainname é o nome do seu locatário; por exemplo, contoso.com. Como esse domínio é usado para acessar o Hub de Eventos do Azure, é importante que ele corresponda ao domínio usado pela assinatura do Azure que contém o Hub de Eventos do Azure. Para obter essas informações, selecione o menu Microsoft Entra ID no portal do Azure e marcar página Visão geral. O nome de domínio é exibido no domínio Primário.

Observação

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

Receber notificações

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

Antes de receber as notificações em seu aplicativo, você precisa criar outra política de acesso compartilhado com uma permissão "Escutar" e obter o cadeia de conexão, semelhante às etapas listadas em Configurar o hub de eventos.

Dica

Create uma política separada para o aplicativo que escuta mensagens dos Hubs de Eventos em vez de reutilização do mesmo cadeia de conexão que você definiu no Azure KeyVault. Essa separação segue o princípio de privilégio mínimo, garantindo que cada componente da solução tenha apenas as permissões necessárias.

Manipulando notificações de validação

Seu aplicativo recebe notificações de validação sempre que cria uma nova assinatura. 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"
            }
        }
    ]
}

Assinaturas para notificações avançadas com grandes cargas

O tamanho máximo da mensagem para Hubs de Eventos é de 1 MB. Ao usar notificações avançadas, você pode esperar notificações que excedam esse limite. Para receber notificações maiores que 1 MB por meio dos Hubs de Eventos, você também deve adicionar uma conta de armazenamento de blobs à sua solicitação de assinatura.

Configurar o armazenamento e criar uma assinatura

1. Create uma conta de armazenamento.
2. Create um contêiner na conta de armazenamento e atribua-lhe um nome.
3. Recupere as chaves ou cadeia de conexão de acesso da conta de armazenamento.
4. Adicione o cadeia de conexão ao cofre de chaves e dê-lhe um nome. Esse valor é o nome secreto.
5. Create ou recriar sua assinatura, agora incluindo 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 uma carga de notificação maior que 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 AdicionalPayloadStorageId com uma ID que aponta para o blob em sua conta de armazenamento em que essas propriedades são armazenadas.

E se o aplicativo Controle de Alterações do Microsoft Graph estiver ausente?

O Microsoft Graph Controle de Alterações entidade de serviço pode estar ausente do locatário, dependendo de quando o locatário foi criado e operações administrativas. O appId globalmente exclusivo da entidade de serviço é 0bf30f3b-4a52-48df-9a82-234910c4a086 e você pode executar a consulta a seguir para confirmar se ela existe no locatário.

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 seu projeto e criar uma instância do authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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 seu projeto e criar uma instância do authProvider .

Ir

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



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 seu projeto e criar uma instância do 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 seu projeto e criar uma instância do authProvider .

JavaScript

Snippet not available

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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 seu projeto e criar uma instância do authProvider .

PowerShell

Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalByAppId

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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 seu projeto e criar uma instância do authProvider .

Se a entidade de serviço não existir, crie-a da seguinte maneira. Você deve conceder ao aplicativo de chamada a permissão Application.ReadWrite.All para executar essa 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 seu projeto e criar uma instância do authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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 seu projeto e criar uma instância do authProvider .

Ir

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewServicePrincipal()
appId := "0bf30f3b-4a52-48df-9a82-234910c4a086"
requestBody.SetAppId(&appId) 

servicePrincipals, err := graphClient.ServicePrincipals().Post(context.Background(), requestBody, nil)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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 seu projeto e criar uma instância do 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 seu projeto e criar uma instância do 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 seu projeto e criar uma instância do 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 seu projeto e criar uma instância do 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 seu projeto e criar uma instância do 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

• Visã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