Compartir vía

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

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" para una canalización de eventos y, una vez recopilados los datos en un hub de eventos, se pueden transformar y almacenar mediante análisis en tiempo real o adaptadores de procesamiento por lotes o 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:

Se recomienda usar las credenciales de identidad administrada siempre que sea posible, para mejorar la seguridad.

Opción 1: Configuración de una 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, anote el identificador de objeto 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. Para asignar el rol, use Azure Portal u otra herramienta de Azure.

Opción 2: Configurar una 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 REST de API Management directamente o mediante otras herramientas, como Azure PowerShell, un archivo de Bicep o una plantilla de Azure Resource Management.

Puede configurar un registrador de API Management en un centro de eventos mediante credenciales de identidad administrada asignadas por el sistema o asignadas por el usuario.

Creación de un registrador con credenciales de identidad administrada asignadas por el sistema

Para conocer los requisitos previos, consulte Configuración de una identidad administrada de API Management.

Use el miembro Logger - Crear o Actualizar de la API de REST 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>"
    }
  }
}

Creación de un registrador con credenciales de identidad administrada asignadas por el usuario

Para conocer los requisitos previos, consulte Configuración de una identidad administrada de API Management.

Use el miembro Logger - Crear o Actualizar de la API de REST 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. Creación de un registrador con credenciales de cadena de conexión

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

Nota:

Se recomienda configurar el registrador con credenciales de identidad administrada siempre que sea posible. Consulte Configuración de un 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.

# Details specific to API Management 
$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"

Configure una política de registro a Event Hub

Una vez que su 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. En API, seleccione API y, a continuación, seleccione la API a la que desea agregar la directiva. En este ejemplo, vamos a agregar una directiva a la API eco en el producto Unlimited (Sin límites).

  3. En la pestaña Diseño , seleccione Todas las operaciones.

  4. En el panel Procesamiento de entrada o Procesamiento saliente , seleccione el <botón /> (Editor de código de directiva). Para más información, consulte Establecimiento o modificación de directivas.

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

  6. Seleccione Mostrar fragmentos en la parte superior de la pestaña. Seleccione Políticas avanzadas>Registrar 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.

  7. Seleccione Guardar para guardar la configuración de la directiva actualizada. En cuanto se guarde la configuración, la directiva está 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 enviado a un centro de eventos es superior a 200 KB, se trunca automáticamente y el mensaje truncado se transfiere al centro de eventos. Para mensajes más grandes, considere la posibilidad de usar Azure Storage con API Management como solución alternativa para omitir el límite de 200 KB. Para más información, consulte Envío de solicitudes a Azure Storage desde API Management.

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. En Azure Portal, vaya al centro de eventos al que el registrador envía eventos.
  2. En Características, seleccione 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.

Contenido relacionado

  • Last updated on