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

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

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 los 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:

• Create 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 un cadena de conexión al centro recién creado.

Pasos:

1. Inicie sesión en la Azure Portal con privilegios para crear recursos en la suscripción de Azure.
2. Seleccione Create un tipo de recurso>Event Hubs en la barra > de búsqueda, seleccione la sugerencia de Event Hubs.
3. En la página de creación de Event Hubs, seleccione Create.
4. Rellene los detalles de creación del espacio de nombres de Event Hubs y, a continuación, seleccione Create.
5. Cuando se aprovisione el espacio de nombres del centro de eventos, vaya a la página del espacio de nombres.
6. Seleccione Event Hubs y + Centro de eventos.
7. Asigne un nombre al nuevo centro de eventos y seleccione Create.
8. Una vez creado el centro de eventos, seleccione el nombre del centro de eventos y, a continuación, seleccione Directivas de acceso compartido y + Agregar para agregar una nueva directiva.
9. Asigne un nombre a la directiva, active Enviar y seleccione Create.
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 del Key Vault de Azure

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

En esta sección, usted:

• Create una Key Vault de Azure para almacenar el secreto.
• Agregue el 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 la Azure Portal con privilegios para crear recursos en la suscripción de Azure.
2. Seleccione Create un tipo de recurso>Key Vault en la barra > de búsqueda, seleccione la sugerencia de Key Vault.
3. En la página de creación de Key Vault, seleccione Create.
4. Rellene los detalles de creación de Key Vault y, a continuación, seleccione Revisar y Create y Create.
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 + Agregar directiva de acceso.
10. Para Permisos secretos, seleccione Obtenery para Seleccionar principal, seleccione Seguimiento de Cambios de Microsoft Graph. Seleccione Agregar.

Uso de la Azure Portal (RBAC)

Configuración del centro de eventos

En esta sección:

• Create 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 un cadena de conexión al centro recién creado.

Pasos:

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

Create la suscripción y recibir 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.

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

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 del centro de eventos. Puede encontrarse 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. Puede encontrarse 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 al Centro de eventos de Azure, es importante que coincida con el dominio que usa la suscripción de Azure que contiene el Centro de eventos de Azure. 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.

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 el cadena de conexión, de forma similar a los pasos enumerados en Configuración del centro de eventos.

Sugerencia

Create una directiva independiente para la aplicación que escucha mensajes de Event Hubs en lugar de reutilizar el mismo cadena de conexión que ha establecido 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. Create una cuenta de almacenamiento.
2. Create un contenedor en la cuenta de almacenamiento y asígnele un nombre.
3. Recupere las claves de acceso de la cuenta de almacenamiento o cadena de conexión.
4. Agregue el cadena de conexión al almacén de claves y asígnele un nombre. Este valor es el nombre del secreto.
5. Create 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.

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

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



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

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

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