Creación de una conexión de datos de Event Grid para Azure Data Explorer

En este artículo, aprenderá a ingerir blobs desde la cuenta de almacenamiento en Azure Data Explorer mediante una conexión de datos de Event Grid. Creará una conexión de datos de Event Grid que establece una suscripción de Azure Event Grid. La suscripción de Event Grid enruta los eventos desde la cuenta de almacenamiento a Azure Data Explorer mediante Azure Event Hubs.

Nota:

La ingesta admite un tamaño de archivo máximo de 6 GB. Se recomienda ingerir archivos de entre 100 MB y 1 GB.

Para obtener información sobre cómo crear la conexión mediante los SDK de Kusto, consulte Crear una conexión de datos de Event Grid con SDK.

Para información general sobre la ingesta en Azure Data Explorer desde Event Grid, consulte Conexión a Event Grid.

Nota:

Para lograr el mejor rendimiento con la conexión de Event Grid, establezca la propiedad de ingesta rawSizeBytes a través de los metadatos del blob. Para obtener más información, vea propiedades de ingesta.

Requisitos previos

• Suscripción a Azure. Cree una cuenta de Azure gratuita.
• Un clúster y la base de datos de Azure Data Explorer. Cree un clúster y una base de datos.
• Una tabla de destino. Cree una tabla o use una tabla existente.
• Una asignación de ingesta para la tabla.
• Una cuenta de almacenamiento. Una suscripción de notificación de Event Grid se puede establecer en cuentas de Azure Storage para BlobStorage, StorageV2 o Data Lake Storage Gen2.
• Tener el proveedor de recursos de Event Grid registrado.

Creación de una conexión de datos de Event Grid

En esta sección, establecerá una conexión entre Event Grid y la tabla de Azure Data Explorer.

Portal: Azure Data Explorer

1. Vaya al clúster de Azure Data Explorer en Azure Portal.

2. En Datos, seleccione Bases de datos>TestDatabase.

   

3. En Configuración, seleccione Conexiones de datos y, a continuación, seleccione Agregar conexión de datos>Event Grid (Blob Storage).

   

4. Rellene el formulario de conexión de datos de Event Grid con la siguiente información:

   

   Configuración	Valor sugerido	Descripción del campo
   Nombre de la conexión de datos	test-grid-connection	Nombre de la conexión que desea crear en Azure Data Explorer. Los nombres de conexiones de datos solo pueden contener caracteres alfanuméricos, guiones y puntos, y tener como máximo 40 caracteres.
   Suscripción de la cuenta de almacenamiento	Su Id. de suscripción	El identificador de la suscripción en la que reside la cuenta de almacenamiento.
   Tipo de evento	Blob creado o Blob con el nombre cambiado	Tipo de evento que desencadena la ingesta. El evento Blob con el nombre cambiado solo se admite para el almacenamiento de ADLSv2. Para cambiar el nombre de un blob, vaya al blob en Azure Portal, haga clic con el botón derecho en el blob y seleccione Cambiar nombre. Estos son los tipos que se admiten: Microsoft.Storage.BlobCreated o Microsoft.Storage.BlobRenamed.
   Cuenta de almacenamiento	gridteststorage1	Nombre de la cuenta de almacenamiento que creó anteriormente.
   Creación de recursos	Automático	Activar la creación automática de recursos significa que Azure Data Explorer crea una suscripción a Event Grid, un espacio de nombres de Event Hubs y Event Hubs automáticamente. De lo contrario, deberá crear estos recursos manualmente para garantizar la creación de la conexión de datos. Consulte Creación manual de recursos para la ingesta de Event Grid

   1. Si lo desea, puede realizar un seguimiento de temas específicos de Event Grid. Establezca los filtros para las notificaciones de la manera siguiente:

      • El campo prefijo es el prefijo literal del asunto. Como el patrón que se aplica es comienza por, puede abarcar varios contenedores, carpetas o blobs. No se permiten comodines.
        • Para definir un filtro en el contenedor de blobs, el campo debe establecerse de la siguiente manera: /blobServices/default/containers/[container prefix].
        • Para definir un filtro en un prefijo de blob (o en una carpeta en Azure Data Lake Gen2), el campo debe establecerse de la siguiente manera: /blobServices/default/containers/[container name]/blobs/[folder/blob prefix].
      • El campo sufijo es el sufijo literal del blob. No se permiten comodines.
      • El campo Distinguir mayúsculas de minúsculas indica si los filtros de prefijos y sufijos distinguen mayúsculas de minúsculas.

      Para obtener más información sobre el filtrado de eventos, consulte Eventos de Blob Storage.

   2. Si lo desea, puede especificar la configuración de enrutamiento de datos de acuerdo con la siguiente información. No es necesario especificar todos los valores de configuración de enrutamiento de datos. También se aceptan configuraciones parciales.

      Configuración	Valor sugerido	Descripción del campo
      Permite el enrutamiento de los datos a otras bases de datos (conexión de datos de varias bases de datos)	No permitir	Active esta opción si desea invalidar la base de datos de destino predeterminada asociada a la conexión de datos. Para más información acerca del enrutamiento de bases de datos, consulte Enrutamiento de eventos.
      Nombre de tabla	TestTable	La tabla que creó en TestDatabase.
      Formato de datos	JSON	Los formatos admitidos son APACHEAVRO, Avro, CSV, JSON, ORC, PARQUET, PSV, RAW, SCSV, SOHSV, TSV, TSVE, TXT y W3CLOG. Las opciones de compresión admitidas son zip y gzip.
      Nombre de asignación	TestTable_mapping	La asignación que creó en TestDatabase, que asigna los datos entrantes a los nombres de columnas y tipos de datos de TestTable. Si no se especifica, se genera automáticamente una asignación de datos de identidad derivada del esquema de la tabla.
      Omitir errores de formato	Ignore	Active esta opción si desea omitir los errores de formato para el formato de datos JSON.

      Nota:

      Los nombres de tabla y de asignación distinguen mayúsculas de minúsculas.

   3. Si lo desea, en Configuración avanzada, puede especificar el tipo de identidad administrada que usa la conexión de datos. De forma predeterminada, se selecciona Asignada por el sistema.

      Si selecciona Asignada por el usuario, deberá asignar manualmente una identidad administrada. Si selecciona un usuario que aún no está asignado al clúster, se le asignará automáticamente. Para obtener más información, consulte Configuración de identidades administradas para el clúster de Azure Data Explorer.

      Si selecciona Ninguna, la cuenta de almacenamiento y el centro de eventos se autenticarán a través de cadenas de conexión. No se recomienda este método.

      

5. Seleccione Crear

Portal: Azure Storage

1. Vaya a la cuenta de almacenamiento en Azure Portal.
2. Seleccione Eventos.
3. En la pestaña Introducción, seleccione la pestaña Azure Data Explorer.
4. En el icono Crear ingesta de datos continua, seleccione Crear.

Elegir el destino al que se enviarán los eventos

1. Seleccione un clúster en el que desea ingerir datos.
2. Selecciona una base de datos de destino.
3. Elija Seleccionar.

Crear conexión de datos

1. Rellene el formulario con la siguiente información:

   

   Configuración	Valor sugerido	Descripción del campo
   Nombre de la conexión de datos	test-grid-connection	Nombre de la conexión que desea crear en Azure Data Explorer.
   Suscripción de la cuenta de almacenamiento	Su Id. de suscripción	El identificador de la suscripción en la que reside la cuenta de almacenamiento.
   Tipo de evento	Blob creado o Blob con el nombre cambiado	Tipo de evento que desencadena la ingesta. El evento Blob con el nombre cambiado solo se admite para el almacenamiento de ADLSv2. Para cambiar el nombre de un blob, vaya al blob en Azure Portal, haga clic con el botón derecho en el blob y seleccione Cambiar nombre. Estos son los tipos que se admiten: Microsoft.Storage.BlobCreated o Microsoft.Storage.BlobRenamed.
   Cuenta de almacenamiento	gridteststorage1	La cuenta de almacenamiento desde la que ha accedido a este asistente se rellena automáticamente.
   Creación de recursos	Automático	Activar la creación automática de recursos significa que Azure Data Explorer crea una suscripción a Event Grid, un espacio de nombres de Event Hubs y Event Hubs automáticamente. De lo contrario, deberá crear estos recursos manualmente para garantizar la creación de la conexión de datos. Consulte Creación manual de recursos para la ingesta de Event Grid

   1. Si lo desea, puede realizar un seguimiento de temas específicos de Event Grid. Establezca los filtros para las notificaciones de la manera siguiente:

      • El campo prefijo es el prefijo literal del asunto. Como el patrón que se aplica es comienza por, puede abarcar varios contenedores, carpetas o blobs. No se permiten comodines.
        • Para definir un filtro en el contenedor de blobs, el campo debe establecerse de la siguiente manera: /blobServices/default/containers/[container prefix].
        • Para definir un filtro en un prefijo de blob (o en una carpeta en Azure Data Lake Gen2), el campo debe establecerse de la siguiente manera: /blobServices/default/containers/[container name]/blobs/[folder/blob prefix].
      • El campo sufijo es el sufijo literal del blob. No se permiten comodines.
      • El campo Distinguir mayúsculas de minúsculas indica si los filtros de prefijos y sufijos distinguen mayúsculas de minúsculas.

      Para obtener más información sobre el filtrado de eventos, consulte Eventos de Blob Storage.

   2. Si lo desea, puede especificar la configuración de enrutamiento de datos de acuerdo con la siguiente información. No es necesario especificar todos los valores de configuración de enrutamiento de datos. También se aceptan configuraciones parciales.

      Configuración	Valor sugerido	Descripción del campo
      Permite el enrutamiento de los datos a otras bases de datos (conexión de datos de varias bases de datos)	No permitir	Active esta opción si desea invalidar la base de datos de destino predeterminada asociada a la conexión de datos. Para más información acerca del enrutamiento de bases de datos, consulte Enrutamiento de eventos.
      Nombre de tabla	TestTable	La tabla que creó en TestDatabase.
      Formato de datos	JSON	Los formatos admitidos son APACHEAVRO, Avro, CSV, JSON, ORC, PARQUET, PSV, RAW, SCSV, SOHSV, TSV, TSVE, TXT y W3CLOG. Las opciones de compresión admitidas son zip y gzip.
      Nombre de asignación	TestTable_mapping	La asignación que creó en TestDatabase, que asigna los datos entrantes a los nombres de columnas y tipos de datos de TestTable. Si no se especifica, se genera automáticamente una asignación de datos de identidad derivada del esquema de la tabla.
      Omitir errores de formato	Ignore	Active esta opción si desea omitir los errores de formato para el formato de datos JSON.

      Nota:

      Los nombres de tabla y de asignación distinguen mayúsculas de minúsculas.

   3. Si lo desea, en Configuración avanzada, puede especificar el tipo de identidad administrada que usa la conexión de datos. De forma predeterminada, se selecciona Asignada por el sistema.

      Si selecciona Asignada por el usuario, deberá asignar manualmente una identidad administrada. Si selecciona un usuario que aún no está asignado al clúster, se le asignará automáticamente. Para obtener más información, consulte Configuración de identidades administradas para el clúster de Azure Data Explorer.

      Si selecciona Ninguna, la cuenta de almacenamiento y el centro de eventos se autenticarán a través de cadenas de conexión. No se recomienda este método.

      

2. Seleccione Crear.

Plantilla ARM

En el ejemplo siguiente se muestra una plantilla de Azure Resource Manager para agregar una conexión de datos de Event Grid. Puede editar e implementar la plantilla en Azure Portal mediante el formulario.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "namespaces_eventhubns_name": {
            "type": "string",
            "defaultValue": "eventhubns",
            "metadata": {
                "description": "Specifies the event hub namespace name."
            }
        },
        "EventHubs_eventhubdemo_name": {
            "type": "string",
            "defaultValue": "eventhubdemo",
            "metadata": {
                "description": "Specifies the event hub name."
            }
        },
        "consumergroup_default_name": {
            "type": "string",
            "defaultValue": "$Default",
            "metadata": {
                "description": "Specifies the consumer group of the event hub."
            }
        },
        "StorageAccounts_storagedemo_name": {
            "type": "string",
            "defaultValue": "storagedemo",
            "metadata": {
                "description": "Specifies the storage account name"
            }
        },
        "Clusters_kustocluster_name": {
            "type": "string",
            "defaultValue": "kustocluster",
            "metadata": {
                "description": "Specifies the name of the cluster"
            }
        },
        "databases_kustodb_name": {
            "type": "string",
            "defaultValue": "kustodb",
            "metadata": {
                "description": "Specifies the name of the database"
            }
        },
        "tables_kustotable_name": {
            "type": "string",
            "defaultValue": "kustotable",
            "metadata": {
                "description": "Specifies the name of the table"
            }
        },
        "mapping_kustomapping_name": {
            "type": "string",
            "defaultValue": "kustomapping",
            "metadata": {
                "description": "Specifies the name of the mapping rule"
            }
        },
        "dataformat_type": {
            "type": "string",
            "defaultValue": "csv",
            "metadata": {
                "description": "Specifies the data format"
            }
        },
             "databaseRouting_type": {
            "type": "string",
            "defaultValue": "Single",
            "metadata": {
                "description": "The database routing for the connection. If you set the value to **Single**, the data connection will be routed to a single database in the cluster as specified in the *databaseName* setting. If you set the value to **Multi**, you can override the default target database using the *Database* EventData property."
            }
        },
        "dataconnections_kustodc_name": {
            "type": "string",
            "defaultValue": "kustodc",
            "metadata": {
                "description": "Name of the data connection to create"
            }
        },
        "subscriptionId": {
            "type": "string",
            "defaultValue": "[subscription().subscriptionId]",
            "metadata": {
                "description": "Specifies the subscriptionId of the resources"
            }
        },
        "resourceGroup": {
            "type": "string",
            "defaultValue": "[resourceGroup().name]",
            "metadata": {
                "description": "Specifies the resourceGroup of the resources"
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "[resourceGroup().location]",
            "metadata": {
                "description": "Location for all resources."
            }
        }
    },
    "variables": {
    },
    "resources": [{
            "type": "Microsoft.Kusto/Clusters/Databases/DataConnections",
            "apiVersion": "2022-02-01",
            "name": "[concat(parameters('Clusters_kustocluster_name'), '/', parameters('databases_kustodb_name'), '/', parameters('dataconnections_kustodc_name'))]",
            "location": "[parameters('location')]",
            "kind": "EventGrid",
            "properties": {
                "managedIdentityResourceId": "[resourceId('Microsoft.Kusto/clusters', parameters('clusters_kustocluster_name'))]",
                "storageAccountResourceId": "[resourceId(parameters('subscriptionId'), parameters('resourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('StorageAccounts_storagedemo_name'))]",
                "eventHubResourceId": "[resourceId(parameters('subscriptionId'), parameters('resourceGroup'), 'Microsoft.EventHub/namespaces/eventhubs', parameters('namespaces_eventhubns_name'), parameters('EventHubs_eventhubdemo_name'))]",
                "consumerGroup": "[parameters('consumergroup_default_name')]",
                "tableName": "[parameters('tables_kustotable_name')]",
                "mappingRuleName": "[parameters('mapping_kustomapping_name')]",
                "dataFormat": "[parameters('dataformat_type')]",
                "databaseRouting": "[parameters('databaseRouting_type')]"
            }
        }
    ]
}

Usar la conexión de datos de Event Grid

En esta sección se muestra cómo desencadenar la ingesta desde Azure Blob Storage o Azure Data Lake Gen 2 al clúster después de la creación del blob o el cambio de nombre del blob.

Seleccione la pestaña pertinente en función del tipo de SDK de almacenamiento que se usa para cargar blobs.

Azure Blob Storage

En el ejemplo de código siguiente se usa el SDK de Azure Blob Storage para cargar un archivo en Azure Blob Storage. La carga desencadena la conexión de datos de Event Grid, que ingiere los datos en Azure Data Explorer.

var azureStorageAccountConnectionString = <storage_account_connection_string>;
var containerName = <container_name>;
var blobName = <blob_name>;
var localFileName = <file_to_upload>;
var uncompressedSizeInBytes = <uncompressed_size_in_bytes>;
var mapping = <mapping_reference>;
// Create a new container if it not already exists.
var azureStorageAccount = new BlobServiceClient(azureStorageAccountConnectionString);
var container = azureStorageAccount.GetBlobContainerClient(containerName);
container.CreateIfNotExists();
// Define blob metadata and uploading options.
IDictionary<String, String> metadata = new Dictionary<string, string>();
metadata.Add("rawSizeBytes", uncompressedSizeInBytes);
metadata.Add("kustoIngestionMappingReference", mapping);
var uploadOptions = new BlobUploadOptions
{
    Metadata = metadata,
};
// Upload the file.
var blob = container.GetBlobClient(blobName);
blob.Upload(localFileName, uploadOptions);

Nota:

Azure Data Explorer no eliminará los blobs con posterioridad a la ingesta. Conserve los blobs de tres a cinco días mediante el ciclo de vida de Azure Blob Storage para administrar la eliminación de blobs.

Azure Data Lake

En el ejemplo de código siguiente se usa el SDK de Azure Data Lake para cargar un archivo en Data Lake Storage Gen2. La carga desencadena la conexión de datos de Event Grid, que ingiere los datos en Azure Data Explorer.

var accountName = <storage_account_name>;
var accountKey = <storage_account_key>;
var fileSystemName = <file_system_name>;
var fileName = <file_name>;
var localFileName = <file_to_upload>;
var uncompressedSizeInBytes = <uncompressed_size_in_bytes>;
var mapping = <mapping_reference>;
var sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
var dfsUri = "https://" + accountName + ".dfs.core.windows.net";
var dataLakeServiceClient = new DataLakeServiceClient(new Uri(dfsUri), sharedKeyCredential);
// Create the filesystem.
var dataLakeFileSystemClient = dataLakeServiceClient.CreateFileSystem(fileSystemName).Value;
// Define file metadata and uploading options.
IDictionary<String, String> metadata = new Dictionary<string, string>();
metadata.Add("rawSizeBytes", uncompressedSizeInBytes);
metadata.Add("kustoIngestionMappingReference", mapping);
var uploadOptions = new DataLakeFileUploadOptions
{
    Metadata = metadata,
    Close = true // Note: The close option triggers the event being processed by the data connection.
};
// Upload the file.
var dataLakeFileClient = dataLakeFileSystemClient.GetFileClient(fileName);
dataLakeFileClient.Upload(localFileName, uploadOptions);

Nota:

• Al cargar un archivo con el SDK de Azure Data Lake, el evento de creación de archivos inicial tiene un tamaño de 0, que Azure Data Explorer omite durante la ingesta de datos. Para garantizar la ingesta adecuada, establezca el parámetro Close en true. Este parámetro hace que el método de carga desencadene un evento FlushAndClose, lo que indica que se ha realizado la actualización final y se cierra la secuencia de archivo.
• Para reducir el tráfico procedente de Event Grid y optimizar la ingesta de eventos en Azure Data Explorer, se recomienda filtrar la clave de data.api para excluir eventos CreateFile. Esto garantiza que los eventos de creación de archivos con el tamaño 0 se filtren, lo que impide errores de ingesta de archivos vacíos. Para más información sobre el vaciado, consulte Método de vaciado de Azure Data Lake.

Cambio del nombre de los blobs

En ADLSv2, es posible cambiar el nombre de los directorios. Sin embargo, es importante tener en cuenta que cambiar el nombre de un directorio no desencadena eventos de cambio de nombre de blobs ni inicia la ingesta de blobs incluidos en el directorio. Si desea garantizar la ingesta de blobs tras cambiar el nombre de un directorio, deberá cambiar directamente el nombre de los blobs individuales dentro del directorio.

En el ejemplo de código siguiente se muestra cómo cambiar el nombre de un blob en una cuenta de almacenamiento de ADLSv2.

var accountName = <storage_account_name>;
var accountKey = <storage_account_key>;
var fileSystemName = <file_system_name>;
var sourceFilePath = <source_file_path>;
var destinationFilePath = <destination_file_path>;
var sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
var dfsUri = "https://" + accountName + ".dfs.core.windows.net";
var dataLakeServiceClient = new DataLakeServiceClient(new Uri(dfsUri), sharedKeyCredential);
// Get a client to the the filesystem

var dataLakeFileSystemClient = dataLakeServiceClient.GetFileSystemClient(fileSystemName);
// Rename a file in the file system
var dataLakeFileClient = dataLakeFileSystemClient.GetFileClient(sourceFilePath);
dataLakeFileClient.Rename(destinationFilePath);

Nota:

Si ha definido filtros para realizar el seguimiento de asuntos específicos al crear la conexión de datos o al crear los recursos de Event Grid manualmente, estos filtros se aplican en la ruta de acceso del archivo de destino.

Nota:

No se admite el desencadenamiento de la ingesta después de una operación CopyBlob para las cuentas de almacenamiento que tienen habilitada la característica de espacio de nombres jerárquico.

Importante

No se recomienda generar eventos de almacenamiento a partir de código personalizado y enviarlos a Event Hubs. Si decide hacerlo, asegúrese de que los eventos producidos cumplen estrictamente el esquema de eventos de almacenamiento y las especificaciones de formato JSON adecuadas.

Eliminar una conexión de datos de Event Grid

Para quitar la conexión de Event Grid desde Azure Portal, siga estos pasos:

1. Vaya al clúster. En el menú de la izquierda, seleccione Bases de datos. A continuación, seleccione la base de datos que contiene la tabla de destino.
2. En el menú de la izquierda, seleccione Conexiones de datos. A continuación, active la casilla situada junto a la conexión de datos de Event Grid correspondiente.
3. Seleccione Eliminar en la barra de menús superior.

---

Contenido relacionado

• Procesamiento de datos de un centro de eventos con Azure Stream Analytics