Recibir notificaciones de cambio a través de Azure Event Hubs

Es posible que los webhooks no sean adecuados para recibir notificaciones de cambio en escenarios de alto rendimiento o cuando el receptor no pueda exponer una dirección URL de notificación disponible públicamente. Como alternativa, puede usar Azure Event Hubs.

Algunos ejemplos de escenarios de alto rendimiento son las aplicaciones que se suscriben a un gran conjunto de recursos, las aplicaciones que se suscriben a recursos que cambian con una frecuencia alta y las aplicaciones multiinquilino que se suscriben a recursos en un gran conjunto de organizaciones.

El artículo le guía por el proceso de administración de la suscripción de Microsoft Graph y cómo recibir notificaciones de cambios a través de Azure Event Hubs.

Usar Azure Event Hubs para recibir notificaciones de cambios

Azure Event Hubs es un conocido servicio de distribución y recopilación de eventos en tiempo real creado para escalar. Puede usar Azure Events Hubs en lugar de los webhooks tradicionales para recibir notificaciones de cambios.
El uso de Azure Event Hubs para recibir notificaciones de cambios difiere de las webhooks de varias maneras, entre las que se incluyen:

• No se basan en URL de notificación expuestos públicamente. El SDK de Event hubs retransmitirá las notificaciones a la aplicación.
• No es necesario responder a la validación de URL de notificación. Puede ignorar el mensaje de validación que recibe.
• Tendrá que aprovisionar un Azure Event Hub.
• Tendrá que aprovisionar un Azure Key Vault.

Configure Azure KeyVault y Azure Event Hubs

Esta sección le guiará a través de la configuración de los servicios de Azure necesarios.

Usar la CLI de Azure

El CLI de Azure le permite ejecutar scripts y automatizar tareas administrativas en Azure. La CLI se puede instalar en el equipo local o ejecutarse directamente desde 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: El script proporcionado aquí es compatible con shells basados en Linux, Windows WSL y Azure Cloud Shell. Se requieren algunas actualizaciones para ejecutarse en shells de Windows.

Uso de Azure Portal

Configuración del centro de eventos de Azure

En esta sección, podrá:

• Crear un espacio de nombres de Azure Event Hub.
• Agregar un concentrador al espacio de nombres que retransmitirá y enviará las notificaciones.
• Agregar una directiva de acceso compartido que le permita obtener una cadena de conexión al centro recién creado.

Pasos:

1. Abra un explorador en el Portal de Azure.
2. Elija Crear un recurso.
3. Escriba Centros de eventos en la barra de búsqueda.
4. Seleccione la sugerencia de Centros de eventos. Se cargará la página de creación de Centros de eventos.
5. En la página creación de centros de eventos, haga clic en Crear.
6. Rellene los detalles de creación del espacio de nombres de los centros de eventos y, a continuación, haga clic en Crear.
7. Cuando se aprovisiona el espacio de nombres del centro de eventos, vaya a la página del espacio de nombres.
8. Haga clic en Centros de eventos y + centro de eventos.
9. Asigne un nombre al nuevo centro de eventos y haga clic en Crear.
10. Una vez creado el centro de eventos, haga clic en el nombre del centro de eventos y, a continuación, haga clic en Directivas de acceso compartido y + Agregar para agregar una nueva directiva.
11. Asigne un nombre a la directiva, seleccione Enviary haga clic en Crear.
12. Después de crear la Directiva, haga clic en el nombre de la Directiva para abrir el panel de detalles y, a continuación, copie el valor Cadena de conexión-clave principal. Anótela. la necesitará en el siguiente paso.

Configuración de la Azure Key Vault

Para poder obtener acceso a un centro de eventos de forma segura y permitir las rotaciones de clave, Microsoft Graph obtiene la cadena de conexión al centro de eventos a través de la Azure Key Vault.
En esta sección, podrá:

• Crear una Azure Key Vault para almacenar secretos.
• Agregar la cadena de conexión al centro de eventos como un secreto.
• Agregar una directiva de acceso para Microsoft Graph para acceder al secreto.

Pasos:

1. Abra un explorador en el Portal de Azure.
2. Elija Crear un recurso.
3. Escriba Bóveda de claves en la barra de búsqueda.
4. Seleccionar la sugerencia de Bóveda de claves. Se cargará la página de creación de la Bóveda de claves.
5. En la página creación de depósito de clave, haga clic en Crear.
6. Rellene los detalles de creación de la bóveda de clave y, a continuación, haga clic en Revisar + crear y Crear.
7. Vaya al depósito clave recién creado con el ir al recursodesde la notificación.
8. Copie el nombre DNS; lo necesitará en el siguiente paso.
9. Vaya a Secretos y haga clic en + Generar/importar.
10. Asigne un nombre al secreto y conserve el nombre más adelante. lo necesitará en el siguiente paso. Para el valor, péguelo en la cadena de conexión que generó en el paso de Event Hubs. Haga clic en Crear.
11. Haga clic en Directivas de acceso y + Agregar Directiva de acceso.
12. Para Permisos secretos, seleccione Obtenery para Seleccionar principal, seleccione Seguimiento de Cambios de Microsoft Graph. Haga clic en Agregar.

Crear la suscripción y recibir notificaciones

Después de crear los servicios necesarios de Azure KeyVault y Azure Event Hubs, podrá crear su suscripción y empezar a recibir notificaciones de cambios a través de Microsoft Azure Event Hubs.

Creación de la subscripción

Las suscripciones para cambiar las notificaciones con centros de eventos son casi idénticas a las notificaciones de cambios con webhooks. La principal diferencia es que se basan en centros de eventos para entregar las notificaciones. Todas las demás operaciones son similares, incluida la creación de la suscripción.

La diferencia principal durante la creación de una suscripción será la notificationUrl. Se debe establecer en EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>, con los valores siguientes:

• azurekeyvaultname -El nombre que proporcionó a la bóveda de claves cuando la creó. Puede encontrarse en el nombre DNS.
• secretname -El nombre que proporcionó al secreto cuando lo creó. Se pueden encontrar en la página de Secretos de la Azure Key Vault.
• domainname -El nombre de su espacio empresarial. por ejemplo, consto.onmicrosoft.com o contoso.com. Ya que este dominio se usará para tener acceso a la Azure Key Vault, es importante que coincida con el dominio usado por la suscripción de Azure que contiene la Azure Key Vault. Para obtener esta información, vaya a la página de información general del Azure Key Vault que creó y haga clic en la suscripción. El nombre de dominio se muestra debajo del campo Directorio.

Recibir notificaciones

Los eventos se enviarán a la aplicación por los centros de eventos. Para obtener más información, consulte recibir eventos en la documentación de Event hubs.

Antes de que pueda recibir las notificaciones en la aplicación, tendrá que crear otra directiva de acceso compartido con un permiso de "escucha" y obtener la cadena de conexión, de forma similar a los pasos que se indican en Configurar el centro de eventos de Azure.

Nota: Crear una directiva independiente para la aplicación que escucha mensajes de los centros de eventos en lugar de volver a usar las mismas cadenas de conexión que se establecen en Azure KeyVault. Esto asegura que todos los componentes de la solución solo tienen los permisos que necesita y siguen el principio de seguridad de permisos mínimos.

Nota: la aplicación recibe mensajes de validación cada vez que crea una nueva suscripción. Debería ignorar esas notificaciones. El ejemplo siguiente representa el cuerpo de un mensaje de validación.

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

¿Qué ocurre si falta la aplicación de Microsoft Graph Change Tracking?

Es posible que la entidad de servicio Seguimiento de cambios de Microsoft Graph no se encuentre en su espacio empresarial, dependiendo de cuándo se creó el espacio empresarial y de las operaciones administrativas. Para resolver este problema, ejecute la siguiente consulta en Microsoft Graph Explorer.

Detalles de la consulta: 0bf30f3b-4a52-48df-9a82-234910c4a086 es el appId global de la aplicación Microsoft Graph Change Tracking.

HTTP

POST 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

var graphClient = new GraphServiceClient(requestAdapter);

var requestBody = new ServicePrincipal
{
	AppId = "0bf30f3b-4a52-48df-9a82-234910c4a086",
};
var result = await graphClient.ServicePrincipals.PostAsync(requestBody);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.appId = "0bf30f3b-4a52-48df-9a82-234910c4a086";

graphClient.servicePrincipals()
	.buildRequest()
	.post(servicePrincipal);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

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

graphClient, err := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new ServicePrincipal();
$requestBody->setAppId('0bf30f3b-4a52-48df-9a82-234910c4a086');



$result = $graphServiceClient->servicePrincipals()->post($requestBody);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

// THE PYTHON SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
client =  GraphServiceClient(request_adapter)

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




result = await client.service_principals.post(request_body = request_body)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Nota: Puede obtener acceso denegado para ejecutar esta consulta. En este caso, seleccione el icono de engranaje situado al lado del nombre de su cuenta en la esquina superior izquierda. Después, seleccione Seleccionar permisos y busque Application.ReadWrite.All. Comprueba el permiso y selecciona Consentimiento. Después de contenerlo, vuelva a ejecutar la solicitud.

Nota: Esta API solo funciona con una cuenta profesional o educativa, en lugar de una cuenta personal. Asegúrese de que ha iniciado sesión con una cuenta de su dominio.

Como alternativa, puede usar el cmdlet New-MgServicePrincipal en Microsoft Graph PowerShell para agregar la entidad de servicio que falta. A continuación, se muestra un script de ejemplo.

Connect-Graph -Scopes "Application.ReadWrite.All"
New-MgServicePrincipal -AppId "0bf30f3b-4a52-48df-9a82-234910c4a086"

Pasos siguientes

Consulte los siguientes iniciadores rápidos de Azure Event Hubs:

• .NET Core
• Java
• Python
• JavaScript