Recevoir des notifications de modification via Azure Event Hubs

  • Article

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.

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

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

Note: Le script fourni ici est compatible avec les interpréteurs de commandes Linux, Windows WSL et Azure Cloud Shell. Il nécessite certaines mises à jour pour s’exécuter dans les interpréteurs de commandes Windows.

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

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

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 attribué au coffre de clés lorsque vous l’avez créé. Vous le trouverez dans le nom DNS.
  • secretname : nom attribué au secret lorsque vous l’avez créé. Vous le trouverez dans la page Secrets du coffre de clés Azure.
  • 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 coffre de clés Azure que vous avez créé et cliquer sur 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 .

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

Create 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

  1. Create un compte de stockage.
  2. Create un conteneur dans le compte de stockage et attribuez-lui un nom.
  3. Récupérez les clés d’accès au compte de stockage ou chaîne de connexion.
  4. Ajoutez le chaîne de connexion au coffre de clés et donnez-lui un nom. Cette valeur est le nom du secret.
  5. Create 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')

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

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

Contenu connexe