Recepción de notificaciones de cambio a través de Azure Event Hubs

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 son las aplicaciones que se suscriben a un gran conjunto de recursos, las aplicaciones que se suscriben a recursos que cambian con frecuencia 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.

Uso de Azure Event Hubs para recibir una notificación 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 instancia de Azure Key Vault 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

Uso de Azure Portal (RBAC)

Configuración del centro de eventos

En esta sección:

• Cree un espacio de nombres de Event Hubs.
• Agregue un centro a ese espacio de nombres para retransmitir y entregar notificaciones.
• Agregue una directiva de acceso compartido que le permita obtener una cadena de conexión al centro recién creado.

Pasos:

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

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

# --------------
# 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. Requiere que algunas actualizaciones se ejecuten en shells de Windows.

Uso de Azure Portal

Configuración del centro de eventos

En esta sección, usted:

• Cree un espacio de nombres de Event Hubs.
• Agregue un centro a ese espacio de nombres para retransmitir y entregar notificaciones.
• Agregue una directiva de acceso compartido que le permita obtener una cadena de conexión al centro recién creado.

Pasos:

1. Inicie sesión en Azure Portal con privilegios para crear recursos en su suscripción de Azure.
2. Seleccione Crear un recurso, escriba Event Hubs en la barra de búsqueda y, a continuación, seleccione la sugerencia de Event Hubs .
3. En la página de creación de Event Hubs, seleccione Crear.
4. Rellene los detalles de creación del espacio de nombres de Event Hubs y, a continuación, seleccione Crear.
5. Cuando se aprovisione el espacio de nombres de Event Hubs, vaya a la página del espacio de nombres.
6. Seleccione Event Hubs y, a continuación , + Centro de eventos.
7. Asigne un nombre al nuevo centro de eventos y seleccione Crear.
8. Una vez creado el centro de eventos, seleccione el nombre del centro de eventos, elija Directivas de acceso compartido y + Agregar para agregar una nueva directiva.
9. Asigne un nombre a la directiva, active Enviar y seleccione Crear.
10. Una vez creada la directiva, seleccione el nombre de la directiva para abrir el panel de detalles y, a continuación, copie el valor de clave principal de cadena de conexión . Registre el valor; lo necesita para el siguiente paso.

Configuración de Azure Key Vault

Para acceder al centro de eventos de forma segura y permitir rotaciones de claves, Microsoft Graph obtiene la cadena de conexión al centro de eventos a través de Azure Key Vault.

En esta sección, usted:

• Cree una instancia de Azure Key Vault para almacenar el secreto.
• Agregue la cadena de conexión al centro de eventos como secreto.
• Agregar una directiva de acceso para Microsoft Graph para acceder al secreto.

Pasos:

1. Inicie sesión en Azure Portal con privilegios para crear recursos en su suscripción de Azure.
2. Seleccione Crear un recurso, escriba Key Vault en la barra de búsqueda y, a continuación, seleccione la sugerencia de Key Vault .
3. En la página de creación de Key Vault, seleccione Crear.
4. Rellene los detalles de creación de Key Vault y, a continuación, seleccione Revisar y crear y crear.
5. Vaya al depósito clave recién creado con el ir al recursodesde la notificación.
6. Copie el nombre DNS; lo necesitará más adelante en este artículo.
7. Vaya a Secretos y seleccione + Generar o importar.
8. Asigne un nombre al secreto y conserve el nombre para más adelante; lo necesitará más adelante en este artículo. Para el valor, péguelo en la cadena de conexión que generó en el paso de Event Hubs. Seleccione Crear.
9. Seleccione Directivas de acceso y, a continuación, + Agregar directiva de acceso.
10. Para Permisos secretos, seleccione Obtenery para Seleccionar principal, seleccione Seguimiento de Cambios de Microsoft Graph. Seleccione Agregar.

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

Después de crear los servicios necesarios de Azure KeyVault y Azure Event Hubs, 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 del control de acceso basado en rol

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 Azure Event Hubs, es importante que coincida con el dominio usado por la suscripción de Azure que contiene Azure Event Hubs. Para obtener esta información, seleccione el menú Microsoft Entra ID en Azure Portal y compruebe la página Información general. El nombre de dominio se muestra en el dominio principal.

Uso de Key Vault

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 usado por la suscripción de Azure que contiene 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.

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 .

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 la 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 los mensajes de Event Hubs en lugar de reutilizar la misma 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

1. Cree una cuenta de almacenamiento.
2. Cree un contenedor en la cuenta de almacenamiento. El nombre del contenedor debe establecerse en microsoft-graph-change-notifications.
3. Recupere las claves de acceso de la cuenta de almacenamiento o la cadena de conexión.
4. Agregue la cadena de conexión al almacén de claves y asígnele un nombre. Este valor es el nombre del secreto.
5. 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 Seguimiento de cambios de Microsoft Graph del inquilino, en función de cuándo se creó 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.

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

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 .

CLI

mgc service-principals-with-app-id get --app-id {app-id}

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

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

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

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

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

Snippet not available

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
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->servicePrincipalsWithAppId('{appId}', )->get()->wait();

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 .

PowerShell

Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalByAppId

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

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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

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 .

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

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

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 .

CLI

mgc service-principals create --body '{\
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"\
}\
'

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

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

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

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

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 .

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

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 .

PowerShell

Import-Module Microsoft.Graph.Applications

$params = @{
	appId = "0bf30f3b-4a52-48df-9a82-234910c4a086"
}

New-MgServicePrincipal -BodyParameter $params

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

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)

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 .

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

Contenido relacionado

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