Recevoir des notifications de modification via Azure Event Hubs

Article
10/14/2024

Les webhooks ne sont pas adaptés à la réception de notifications de modification dans les scénarios à débit élevé ou lorsque le destinataire ne peut pas exposer une URL de notification disponible publiquement. Vous pouvez également utiliser Azure Event Hubs.

Les exemples de scénarios à débit élevé où vous pouvez utiliser Azure Event Hubs incluent les applications qui s’abonnent à un grand ensemble de ressources, les applications qui s’abonnent à des ressources qui changent fréquemment et les applications multilocataires qui s’abonnent à des ressources dans un grand ensemble d’organisations.

L’article vous guide tout au long du processus de gestion de votre abonnement Microsoft Graph et comment recevoir des notifications de modification via Azure Event Hubs.

Importante

L’authentification d’Event Hubs à l’aide de signatures d’accès partagé (SAP) sera déconseillée à l’avenir. Nous vous recommandons d’authentifier Event Hubs en utilisant Microsoft Entra ID contrôle d’accès en fonction du rôle (RBAC) à la place.

Utilisation de Azure Event Hubs pour recevoir une notification de modification

Azure Event Hubs est un service populaire d’intégration et de distribution d’événements en temps réel conçu pour une mise à l’échelle. L’utilisation d’Azure Event Hubs pour recevoir des notifications de modification diffère des webhooks de plusieurs façons, notamment :

Vous ne dépendez pas des URL de notification exposées publiquement. Le Kit de développement logiciel (SDK) Event Hubs transmet les notifications à votre application.
Vous n’avez pas besoin de répondre aux notifications de validation de l’URL. Vous pouvez ignorer le message de validation que vous recevez.
Vous devez provisionner un hub d’événements.
Vous devez provisionner un Key Vault Azure ou ajouter le service de Change Tracking Microsoft Graph au rôle Expéditeur de données sur votre hub d’événements.

Configurer l’authentification Azure Event Hubs

Azure Event Hubs prend en charge l’authentification via des signatures d’accès partagé (SAP) ou Microsoft Entra ID contrôle d’accès en fonction du rôle (RBAC). Pour plus d’informations, consultez Autoriser l’accès à Azure Event Hubs.

Cette section montre comment configurer l’authentification Azure Event Hubs à l’aide de Microsoft Entra ID contrôle d’accès en fonction du rôle (RBAC) sur le Portail Azure.

Configurer le hub d’événements

Connectez-vous au Portail Azure avec des privilèges pour créer des ressources dans votre abonnement Azure.
Sélectionnez Créer une ressource, tapez Event Hubs dans la barre de recherche, puis sélectionnez la suggestion Event Hubs .
Dans la page de création d’Event Hubs, sélectionnez Créer.
Renseignez les détails de la création de l’espace de noms Event Hubs, puis sélectionnez Créer.
Lorsque l’espace de noms Event Hubs est provisionné, accédez à la page de l’espace de noms.
Sélectionnez Event Hubs , puis + Event Hub.
Donnez un nom au nouveau hub d’événements, puis sélectionnez Créer.
Une fois le hub d’événements créé, accédez à l’espace de noms Event Hubs, puis sélectionnez Access Control (IAM) dans la barre latérale.
Sélectionnez Attributions de rôles.
Sélectionnez + Ajouter , puis Ajouter une attribution de rôle.
Sous Rôle, accédez à Rôles de fonction de travail, sélectionnez Azure Event Hubs Expéditeur de données, puis sélectionnez Suivant.
Sous l’onglet Membres , sélectionnez Attribuer l’accès à l’utilisateur, au groupe ou au principal du service.
Sélectionnez + Sélectionner des membres, puis recherchez et sélectionnez Microsoft Graph Change Tracking.
Sélectionnez Vérifier + affecter pour terminer le processus.

Cette section montre comment configurer l’authentification Azure Event Hubs à l’aide de signatures d’accès partagé (SAP) via Azure CLI.

Azure CLI vous permet de générer des scripts et d’automatiser des tâches d’administration dans Azure. Azure CLI – Interface de ligne de commande Azure peut être installée sur votre ordinateur local ou exécutée directement à partir d’Azure Cloud Shell.

Importante

L’authentification d’Event Hubs à l’aide de signatures d’accès partagé (SAP) sera déconseillée à l’avenir. Nous vous recommandons d’utiliser Microsoft Entra ID contrôle d’accès en fonction du rôle (RBAC) à la place. Suivez les instructions pour migrer vers 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}"

Créer l’abonnement et recevoir des notifications

Après avoir créé les services Azure KeyVault et Azure Event Hubs requis, vous pouvez maintenant créer votre abonnement aux notifications de modification et commencer à recevoir des notifications de modification via Azure Event Hubs.

Créer l’abonnement

La création d’un abonnement pour recevoir des notifications de modification avec Event Hubs est presque identique à la création d’un abonnement webhook, mais avec des modifications importantes apportées à la propriété notificationUrl . Passez d’abord en revue les étapes de création d’un abonnement webhook avant de continuer.

Lors de la création de l’abonnement, la notificationUrl doit pointer vers votre emplacement Event Hubs.

Utilisation du contrôle d’accès en fonction du rôle
Utilisation de Key Vault

Si vous utilisez le contrôle d’accès en fonction du rôle, la propriété notificationUrl se présente comme suit :

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

<eventhubnamespace> est le nom que vous donnez à l’espace de noms Event Hubs. Il se trouve dans la page Vue d’ensemble d’Event Hubs sous Nom d’hôte.
<eventhubname> est le nom que vous donnez au hub d’événements. Il se trouve dans Event Hubs -> Vue d’ensemble -> Event Hubs.
<domainname> est le nom de votre locataire ; par exemple, contoso.com. Étant donné que ce domaine est utilisé pour accéder aux Azure Event Hubs, il est important qu’il corresponde au domaine utilisé par l’abonnement Azure qui détient le Azure Event Hubs. Pour obtenir ces informations, sélectionnez le menu Microsoft Entra ID dans le Portail Azure et case activée la page Vue d’ensemble. Le nom de domaine s’affiche sous le domaine principal.

Si vous utilisez Key Vault, la propriété notificationUrl se présente comme suit : EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>, avec les valeurs suivantes :

<azurekeyvaultname> - Nom que vous avez donné au coffre de clés lors de la création. Il se trouve dans le nom DNS.
<secretname> - Nom que vous avez donné au secret lors de la création. Vous pouvez le trouver dans la page Azure Key Vault Secrets.
<domainname> - Le nom de votre locataire ; par exemple, contoso.com. Étant donné que ce domaine est utilisé pour accéder à l’Key Vault Azure, il est important qu’il corresponde au domaine utilisé par l’abonnement Azure qui détient le Key Vault Azure. Pour obtenir ces informations, vous pouvez accéder à la page de vue d’ensemble du Key Vault Azure que vous avez créé et sélectionner l’abonnement. Le nom de domaine s’affiche sous le champ Répertoire.

Remarque

Les abonnements en double ne sont pas autorisés. Lorsqu’une demande d’abonnement contient les mêmes valeurs pour changeType et resource qu’un abonnement existant, la requête échoue avec un code 409 Conflictd’erreur HTTP et le message Subscription Id <> already exists for the requested combinationd’erreur .

Migrer une authentification event hub vers Microsoft Entra ID RBAC

Cette section vous guide tout au long de la migration de vos hubs d’événements existants avec l’authentification SAS vers Microsoft Entra ID l’authentification RBAC. Utilisez le même espace de noms Event Hub que celui que vous avez utilisé avec l’authentification SAS, via Azure CLI ou l’Portail Azure.

Sous le même espace de noms event hub que celui que vous utilisez pour votre abonnement existant, créez un hub d’événements.
Créez un abonnement avec les mêmes détails que l’abonnement existant, sauf en utilisant le nom du nouveau hub d’événements de l’étape précédente dans l’URL. Pour plus d’informations, consultez Créer l’abonnement : utilisation de RBAC.

Vous recevrez des notifications sur le nouveau hub d’événements. Vous pouvez vérifier si le trafic ressemble à l’ancien abonnement en inspectant le graphique Messages du hub d’événements. Vérifiez également les erreurs ou échecs lors de la réception de notifications.

Une fois que vous avez vérifié que vous recevez des notifications et que le nouveau hub d’événements fonctionne correctement, vous pouvez supprimer l’ancien abonnement, l’ancien hub d’événements et l’authentification basée sur SAS et commencer à utiliser le nouveau.

Recevoir des notifications

Les notifications de modification sont désormais remises à votre application par Event Hubs. Si vous souhaitez obtenir plus d’informations, voir Réception des événements dans la documentation relative aux hubs d’événements.

Avant de recevoir les notifications dans votre application, vous devez créer une autre stratégie d’accès partagé avec une autorisation « Écouter » et obtenir le chaîne de connexion, comme dans la procédure décrite dans Configurer le hub d’événements.

Conseil

Créez une stratégie distincte pour l’application qui écoute les messages Event Hubs au lieu de réutiliser les mêmes chaîne de connexion que vous définissez dans Azure KeyVault. Cette séparation suit le principe du privilège minimum en garantissant que chaque composant de la solution dispose uniquement des autorisations dont il a besoin.

Gestion des notifications de validation

Votre application reçoit des notifications de validation chaque fois qu’elle crée un abonnement. Vous devez ignorer ces notifications. L’exemple suivant représente le contenu d’un message de validation.

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

Abonnements pour les notifications enrichies avec des charges utiles volumineuses

La taille maximale des messages pour Event Hubs est de 1 Mo. Lorsque vous utilisez des notifications enrichies, vous pouvez vous attendre à des notifications qui dépassent cette limite. Pour recevoir des notifications supérieures à 1 Mo via Event Hubs, vous devez également ajouter un compte de stockage d’objets blob à votre demande d’abonnement.

Configurer le stockage et créer un abonnement

Créez un compte de stockage.
Créez un conteneur dans le compte de stockage. Le nom du conteneur doit être défini sur microsoft-graph-change-notifications.
Récupérez les clés d’accès au compte de stockage ou chaîne de connexion.
Ajoutez le chaîne de connexion au coffre de clés et donnez-lui un nom. Cette valeur est le nom du secret.
Créez ou recréez votre abonnement, en incluant maintenant la propriété blobStoreUrl dans la syntaxe suivante : blobStoreUrl: "https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>"

Recevoir des notifications enrichies

Quand Event Hubs reçoit une charge utile de notification supérieure à 1 Mo, la notification ne contient pas les propriétés resource, resourceData et encryptedContent incluses dans les notifications enrichies. La notification contient plutôt une propriétéPayloadStorageId supplémentaire avec un ID qui pointe vers l’objet blob dans votre compte de stockage où ces propriétés sont stockées.

Que se passe-t-il si l’application Microsoft Graph Change Tracking est manquante ?

Le principal de service Microsoft Graph Change Tracking peut être manquant dans votre locataire, en fonction du moment où le locataire a été créé et des opérations d’administration. Le appId global unique du principal de service est 0bf30f3b-4a52-48df-9a82-234910c4a086 et vous pouvez exécuter la requête suivante pour vérifier s’il existe dans le locataire.

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



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

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://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

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

Si le principal de service n’existe pas, créez-le comme suit. Vous devez accorder à l’application appelante l’autorisation Application.ReadWrite.All pour exécuter cette opération.

Méthode 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://learn.microsoft.com/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://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);


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

Méthode 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"
}

Vue d’ensemble des notifications de modification
Consultez les guides de démarrage rapide Azure Event Hubs suivants :
- .NET Core
- Java
- Python
- JavaScript

Partager via

Recevoir des notifications de modification via Azure Event Hubs

Utilisation de Azure Event Hubs pour recevoir une notification de modification

Configurer l’authentification Azure Event Hubs

Configurer le hub d’événements

Configurer le hub d’événements

Configurer le Key Vault Azure

Créer l’abonnement et recevoir des notifications

Créer l’abonnement

Migrer une authentification event hub vers Microsoft Entra ID RBAC

Recevoir des notifications

Gestion des notifications de validation

Abonnements pour les notifications enrichies avec des charges utiles volumineuses

Configurer le stockage et créer un abonnement

Recevoir des notifications enrichies

Que se passe-t-il si l’application Microsoft Graph Change Tracking est manquante ?

Commentaires

Ressources supplémentaires

Partager via

Recevoir des notifications de modification via Azure Event Hubs

Utilisation de Azure Event Hubs pour recevoir une notification de modification

Configurer l’authentification Azure Event Hubs

Configurer le hub d’événements

Créer l’abonnement et recevoir des notifications

Créer l’abonnement

Migrer une authentification event hub vers Microsoft Entra ID RBAC

Recevoir des notifications

Gestion des notifications de validation

Abonnements pour les notifications enrichies avec des charges utiles volumineuses

Configurer le stockage et créer un abonnement

Recevoir des notifications enrichies

Que se passe-t-il si l’application Microsoft Graph Change Tracking est manquante ?

Contenu connexe

Commentaires

Ressources supplémentaires