Compartir vía

Cómo registrar eventos en Azure Event Hubs en Azure API Management

  • Artículo

SE APLICA A: todos los niveles de API Management

En este artículo se describe cómo registrar eventos de API Management mediante Azure Event Hubs.

Azure Event Hubs es un servicio de introducción de datos altamente escalable que permite la introducción de millones de eventos por segundo para que pueda procesar y analizar grandes cantidades de datos generados por los dispositivos y aplicaciones conectados. Event Hubs actúa como la "puerta principal" de una canalización de eventos y, una vez que los datos se recopilan en un centro de eventos, se pueden transformar y almacenar con cualquier proveedor de análisis en tiempo real o adaptadores de procesamiento por lotes/almacenamiento. Event Hubs desacopla la producción de un flujo de eventos desde el consumo de los eventos, para que los consumidores de eventos pueden tener acceso a los eventos según su propia programación.

Nota:

Actualmente, esta característica no está disponible en las áreas de trabajo.

Requisitos previos

Configuración del acceso al centro de eventos

Para registrar eventos en el centro de eventos, debe configurar las credenciales de acceso desde API Management. API Management admite cualquiera de los dos mecanismos de acceso siguientes:

  • Una identidad administrada para la instancia de API Management (recomendado)
  • Una cadena de conexión de Event Hubs

Nota:

Siempre que sea posible, Microsoft recomienda usar credenciales de identidad administrada para una seguridad mejorada.

Opción 1: configuración de la identidad administrada de API Management

  1. Habilite una identidad administrada asignada por el sistema o por el usuario para API Management en la instancia de API Management.

    • Si habilita una identidad administrada asignada por el usuario, tome nota del id. de cliente de la identidad.

  2. Asigne la identidad al rol emisor de Azure Event Hubs, con ámbito al espacio de nombres de Event Hubs o al centro de eventos usado para el registro. Puede usar Azure Portal u otras herramientas de Azure para asignar el rol.

Opción 2: configuración de la cadena de conexión de Event Hubs

Para crear una cadena de conexión de Event Hubs, consulte Obtener una cadena de conexión de Event Hubs.

  • Puede usar una cadena de conexión para el espacio de nombres de Event Hubs o para el centro de eventos específico que use para el registro desde API Management.
  • La directiva de acceso compartido para la cadena de conexión debe habilitar al menos permisos de Envío.

Creación de un registrador de administración de API

El siguiente paso es configurar un registrador en el servicio Administración de API para que se puedan registrar eventos en el centro de eventos.

Cree y administre registradores de API Management mediante la API de REST de API Management directamente o mediante herramientas como Azure PowerShell, una plantilla de Bicep o una plantilla de Azure Resource Management.

Es posible configurar un registrador de API Management en un centro de eventos mediante credenciales de identidad administrada asignada por el usuario o por el sistema.

Registrador con credenciales de identidad administrada asignadas por el sistema

Para conocer los requisitos previos, consulteConfiguración de la identidad administrada de API Management.

Use la API de REST Registrador: crear o actualizar de API Management con el siguiente cuerpo de solicitud.

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "Event Hub logger with system-assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"SystemAssigned",
         "name":"<EventHubName>"
    }
  }
}

Registrador con credenciales de identidad administrada asignadas por el usuario

Para conocer los requisitos previos, consulteConfiguración de la identidad administrada de API Management.

Use la API de REST Registrador: crear o actualizar de API Management con el siguiente cuerpo de solicitud.

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "Event Hub logger with user-assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"<ClientID>",
         "name":"<EventHubName>"
    }
  }
}

Opción 2. Registrador con credenciales de cadena de conexión

Para conocer los requisitos previos, consulte Configuración de la cadena de conexión de Event Hubs.

Nota:

Siempre que sea posible, Microsoft recomienda configurar el registrador con credenciales de identidad administrada. Consulte Configuración del registrador con credenciales de identidad administrada, anteriormente en este artículo.

En el ejemplo siguiente se usa el cmdlet New-AzApiManagementLogger para crear un registrador en un centro de eventos mediante la configuración de una cadena de conexión.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# Create logger
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName
New-AzApiManagementLogger -Context $context -LoggerId "ContosoLogger1" -Name "ApimEventHub" -ConnectionString "Endpoint=sb://<EventHubsNamespace>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>" -Description "Event hub logger with connection string"

Configuración de la directiva log-to-eventhub

Una vez que el registrador está configurado en API Management, puede configurar la directiva log-to-eventhub para registrar los eventos deseados. Por ejemplo, use la directiva log-to-eventhub en la sección directiva de entrada para registrar solicitudes o en la sección directiva de salida para registrar las respuestas.

  1. Vaya a la instancia de API Management.

  2. Seleccione API y después, la API a la que quiere agregar la directiva. En este ejemplo, vamos a agregar una directiva a la API eco en el producto Unlimited (Sin límites).

  3. Seleccione Todas las operaciones.

  4. En la parte superior de la pantalla, seleccione la pestaña Diseño.

  5. En la ventana Procesamiento de entrada o Procesamiento saliente, seleccione el icono </> (editor de código). Para más información, consulte Establecimiento o modificación de directivas.

  6. Coloque el cursor en la sección de directiva inbound o outbound.

  7. En la ventana de la derecha, seleccione Advanced policies> (Directivas avanzadas) Log to EventHub (Registro en EventHub). Esta acción inserta la plantilla de declaración de directiva log-to-eventhub.

    <log-to-eventhub logger-id="logger-id">
    @{
        return new JObject(
            new JProperty("EventTime", DateTime.UtcNow.ToString()),
            new JProperty("ServiceName", context.Deployment.ServiceName),
            new JProperty("RequestId", context.RequestId),
            new JProperty("RequestIp", context.Request.IpAddress),
            new JProperty("OperationName", context.Operation.Name)
        ).ToString();
    }
</log-to-eventhub>
    1. Sustituya logger-id por el nombre del registrador que creó en el paso anterior.
    2. Puede usar cualquier expresión que devuelva una cadena como valor para el elemento log-to-eventhub. En este ejemplo, se registra una cadena en formato JSON que contiene la fecha y hora, el nombre del servicio, el identificador de la solicitud, la dirección IP de la solicitud y el nombre de la operación.

  8. Seleccione Guardar para guardar la configuración de la directiva actualizada. En el momento de guardarla, la directiva se activa y los eventos se registran en el centro de eventos designado.

Nota

El tamaño máximo admitido para los mensajes que se pueden enviar a un centro de eventos desde esta directiva de API Management es de 200 kilobytes (KB). Si un mensaje que se envía a un centro de eventos tiene un tamaño superior a 200 KB, se truncará automáticamente, y el mensaje truncado se transferirá al centro de eventos. Para mensajes más grandes, considere la posibilidad de usar Azure Storage con Azure API Management como solución alternativa para omitir el límite de 200 KB. Se puede encontrar más información en este artículo.

Vista previa del registro en Event Hubs mediante Azure Stream Analytics

Puede obtener una vista previa del registro en Event Hubs mediante consultas de Azure Stream Analytics.

  1. Desde Azure Portal, busque el centro de eventos al que el registrador envía eventos.
  2. En Características, seleccione la pestaña Procesar datos.
  3. En la tarjeta Habilitar conclusiones en tiempo real de eventos, seleccione Iniciar.
  4. Debe poder obtener una vista previa del registro en la pestaña Vista previa de entrada. Si los datos que se muestran no están actualizados, seleccione Actualizar para ver los eventos más recientes.

Pasos siguientes