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

Artículo
10/14/2024

Los webhooks no son adecuados para recibir notificaciones de cambio en escenarios de alto rendimiento o cuando el receptor no puede 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 en los que puede usar Azure Event Hubs incluyen aplicaciones que se suscriben a un gran conjunto de recursos, aplicaciones que se suscriben a recursos que cambian con frecuencia y 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.

Importante

La autenticación de Event Hubs mediante firmas de acceso compartido (SAS) quedará en desuso en el futuro. Se recomienda autenticar Event Hubs mediante Microsoft Entra ID control de acceso basado en rol (RBAC) en su lugar.

Uso de Azure Event Hubs para recibir notificaciones de cambio

Azure Event Hubs es un conocido servicio de distribución y recopilación de eventos en tiempo real creado para escalar. 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 retransmite 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.
Debe aprovisionar un centro de eventos.
Debe aprovisionar una Key Vault de Azure o agregar el servicio Change Tracking de Microsoft Graph al rol Remitente de datos en el centro de eventos.

Configuración de la autenticación de Azure Event Hubs

Azure Event Hubs admite la autenticación mediante firmas de acceso compartido (SAS) o Microsoft Entra ID control de acceso basado en rol (RBAC). Para obtener más información, consulte Autorización del acceso a Azure Event Hubs.

En esta sección se muestra cómo configurar la autenticación de Azure Event Hubs mediante Microsoft Entra ID control de acceso basado en rol (RBAC) en el Azure Portal.

Configuración del centro de eventos

Inicie sesión en la Azure Portal con privilegios para crear recursos en la suscripción de Azure.
Seleccione Crear un recurso, escriba Event Hubs en la barra de búsqueda y, a continuación, seleccione la sugerencia de Event Hubs .
En la página de creación de Event Hubs, seleccione Crear.
Rellene los detalles de creación del espacio de nombres de Event Hubs y, a continuación, seleccione Crear.
Cuando se aprovisione el espacio de nombres de Event Hubs, vaya a la página del espacio de nombres.
Seleccione Event Hubs y, a continuación , + Centro de eventos.
Asigne un nombre al nuevo centro de eventos y seleccione Crear.
Una vez creado el centro de eventos, vaya al espacio de nombres de Event Hubs y, a continuación, seleccione Access Control (IAM) en la barra lateral.
Seleccione Asignaciones de roles.
Seleccione + Agregar y agregar asignación de roles.
En Rol, vaya a Roles de función de trabajo, seleccione Azure Event Hubs Remitente de datos y, a continuación, seleccione Siguiente.
En la pestaña Miembros , seleccione Asignar acceso al usuario, grupo o entidad de servicio.
Seleccione + Seleccionar miembros, busque y seleccione Microsoft Graph Change Tracking.
Seleccione Revisar y asignar para completar el proceso.

En esta sección se muestra cómo configurar Azure Event Hubs autenticación mediante firmas de acceso compartido (SAS) a través de la CLI de Azure.

La CLI de Azure permite crear scripts y automatizar tareas administrativas en Azure. La CLI se puede instalar en el equipo local o ejecutarse directamente desde Azure Cloud Shell.

Importante

La autenticación de Event Hubs mediante firmas de acceso compartido (SAS) quedará en desuso en el futuro. Se recomienda usar Microsoft Entra ID control de acceso basado en rol (RBAC) en su lugar. Siga las instrucciones para migrar a 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}"

Creación de la suscripción y recepción de notificaciones

Después de crear los servicios de Azure KeyVault y Azure Event Hubs necesarios, ahora puede crear la suscripción de notificación de cambios y empezar a recibir notificaciones de cambio a través de Azure Event Hubs.

Creación de la suscripción

La creación de una suscripción para recibir notificaciones de cambios con Event Hubs es casi idéntica a la creación de la suscripción de webhook, pero con cambios importantes en la propiedad notificationUrl . Revise primero los pasos de creación de suscripciones de webhook antes de continuar.

En la creación de la suscripción, notificationUrl debe apuntar a la ubicación de Event Hubs.

Uso de RBAC
Uso de Key Vault

Si usa el control de acceso basado en rol, la propiedad notificationUrl tiene el siguiente aspecto:

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

<eventhubnamespace> es el nombre que se asigna al espacio de nombres de Event Hubs. Se puede encontrar en la página Información general de Event Hubs en Nombre de host.
<eventhubname> es el nombre que se asigna al centro de eventos. Se puede encontrar en Event Hubs:> Información general:> Event Hubs.
<domainname> es el nombre del inquilino; por ejemplo, contoso.com. Dado que este dominio se usa para acceder a la Azure Event Hubs, es importante que coincida con el dominio usado por la suscripción de Azure que contiene el Azure Event Hubs. Para obtener esta información, seleccione el menú Microsoft Entra ID en el Azure Portal y compruebe la página Información general. El nombre de dominio se muestra en el dominio principal.

Si usa Key Vault, la propiedad notificationUrl tiene el siguiente aspecto: EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>, con los siguientes valores:

<azurekeyvaultname> - El nombre que dio al almacén de claves durante la creación. Se puede encontrar en el nombre DNS.
<secretname> - El nombre que le dio al secreto durante la creación. Se puede encontrar en la página Secretos de Azure Key Vault.
<domainname> - El nombre del inquilino; por ejemplo, contoso.com. Dado que este dominio se usa para acceder a azure Key Vault, es importante que coincida con el dominio que usa la suscripción de Azure que contiene la Key Vault de Azure. Para obtener esta información, puede ir a la página de información general de azure Key Vault ha creado y seleccionar la suscripción. El nombre de dominio se muestra debajo del campo Directorio.

Nota:

No se permiten suscripciones duplicadas. Cuando una solicitud de suscripción contiene los mismos valores para changeType y el recurso que contiene una suscripción existente, se produce un error en la solicitud con un código 409 Conflictde error HTTP y el mensaje Subscription Id <> already exists for the requested combinationde error .

Migración de una autenticación del centro de eventos a Microsoft Entra ID RBAC

Esta sección le guía por cómo migrar event hubs existentes con autenticación SAS a Microsoft Entra ID autenticación de RBAC. Use el mismo espacio de nombres del centro de eventos que usó con la autenticación sas, ya sea mediante la CLI de Azure o el Azure Portal.

En el mismo espacio de nombres del centro de eventos que usa para la suscripción existente, cree un nuevo centro de eventos.
Cree una nueva suscripción con los mismos detalles que la existente, excepto con el nombre del nuevo centro de eventos del paso anterior en la dirección URL. Para obtener más información, consulte Creación de la suscripción: uso de RBAC.

Recibirá notificaciones en el nuevo centro de eventos. Puede validar si el tráfico es similar a la suscripción anterior inspeccionando el gráfico Mensajes del centro de eventos. Valide también si hay errores o errores en la recepción de notificaciones.

Después de validar que recibe notificaciones y que el nuevo centro de eventos funciona correctamente, puede eliminar la suscripción antigua, el centro de eventos antiguo y la autenticación basada en SAS y empezar a usar la nueva.

Recibir notificaciones

Event Hubs entrega ahora las notificaciones de cambio a la aplicación. Para obtener más información, consulte recibir eventos en la documentación de Event hubs.

Para poder recibir las notificaciones en la aplicación, debe crear otra directiva de acceso compartido con un permiso "Escuchar" y obtener el cadena de conexión, de forma similar a los pasos enumerados en Configuración del centro de eventos.

Sugerencia

Cree una directiva independiente para la aplicación que escuche mensajes de Event Hubs en lugar de reutilizar el mismo cadena de conexión que estableció en Azure KeyVault. Esta separación sigue el principio de privilegios mínimos al asegurarse de que cada componente de la solución solo tiene los permisos que necesita.

Control de notificaciones de validación

La aplicación recibe notificaciones 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"
            }
        }
    ]
}

Suscripciones para notificaciones enriquecidas con cargas grandes

El tamaño máximo del mensaje para Event Hubs es de 1 MB. Cuando se usan notificaciones enriquecidas, es posible que se esperen notificaciones que superen este límite. Para recibir notificaciones de más de 1 MB a través de Event Hubs, también debe agregar una cuenta de almacenamiento de blobs a la solicitud de suscripción.

Configuración del almacenamiento y creación de una suscripción

Cree una cuenta de almacenamiento.
Cree un contenedor en la cuenta de almacenamiento. El nombre del contenedor debe establecerse en microsoft-graph-change-notifications.
Recupere las claves de acceso de la cuenta de almacenamiento o cadena de conexión.
Agregue el cadena de conexión al almacén de claves y asígnele un nombre. Este valor es el nombre del secreto.
Cree o vuelva a crear la suscripción, incluida ahora la propiedad blobStoreUrl en la sintaxis siguiente: blobStoreUrl: "https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>"

Recepción de notificaciones enriquecidas

Cuando Event Hubs recibe una carga de notificación de más de 1 MB, la notificación no contiene las propiedades resource, resourceData y encryptedContent que se incluyen en notificaciones enriquecidas. En su lugar, la notificación contiene una propiedad additionalPayloadStorageId con un identificador que apunta al blob de la cuenta de almacenamiento donde se almacenan estas propiedades.

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

Es posible que falte la entidad de servicio de Microsoft Graph Change Tracking del inquilino, en función de cuándo se haya creado el inquilino y de las operaciones administrativas. El appId único global de la entidad de servicio es 0bf30f3b-4a52-48df-9a82-234910c4a086 y puede ejecutar la siguiente consulta para confirmar si existe en el inquilino.

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 la entidad de servicio no existe, créela como se indica a continuación. Debe conceder a la aplicación que realiza la llamada el permiso Application.ReadWrite.All para ejecutar esta operación.

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

Introducción a las notificaciones de cambios
Consulte los siguientes iniciadores rápidos de Azure Event Hubs:
- .NET Core
- Java
- Python
- JavaScript

Compartir a través de

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

Uso de Azure Event Hubs para recibir notificaciones de cambio

Configuración de la autenticación de Azure Event Hubs

Configuración del centro de eventos

Configuración del centro de eventos

Configuración del Key Vault de Azure

Creación de la suscripción y recepción de notificaciones

Creación de la suscripción

Migración de una autenticación del centro de eventos a Microsoft Entra ID RBAC

Recibir notificaciones

Control de notificaciones de validación

Suscripciones para notificaciones enriquecidas con cargas grandes

Configuración del almacenamiento y creación de una suscripción

Recepción de notificaciones enriquecidas

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

Comentarios

Recursos adicionales

Compartir a través de

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

Uso de Azure Event Hubs para recibir notificaciones de cambio

Configuración de la autenticación de Azure Event Hubs

Configuración del centro de eventos

Creación de la suscripción y recepción de notificaciones

Creación de la suscripción

Migración de una autenticación del centro de eventos a Microsoft Entra ID RBAC

Recibir notificaciones

Control de notificaciones de validación

Suscripciones para notificaciones enriquecidas con cargas grandes

Configuración del almacenamiento y creación de una suscripción

Recepción de notificaciones enriquecidas

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

Contenido relacionado

Comentarios

Recursos adicionales