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

Artículo
02/29/2024

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 Creación de 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 rawSizeBytes propiedad de ingesta 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 una 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. Se puede establecer una suscripción de notificación de Event Grid en las cuentas de Azure Storage para BlobStorage, StorageV2o Data Lake Storage Gen2.
Tenga registrado el proveedor de recursos de Event Grid.

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.

Vaya al clúster de Azure Data Explorer en el Azure Portal.
En Datos, seleccione Bases de> datosTestDatabase.
En Configuración, seleccione Conexiones de datos y, después, Agregar conexión> de datosEvent Grid (Blob Storage).

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 conexión de datos solo pueden contener caracteres alfanuméricos, guiones y puntos, y tener hasta 40 caracteres de longitud.
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 un centro de eventos automáticamente. De lo contrario, debe 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.

Opcionalmente, 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. A medida que se inicia el patrón aplicado, 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: .
  - 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: .
- 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 más información sobre el filtrado de eventos, consulte Eventos de Blob Storage.

Opcionalmente, puede especificar la configuración de enrutamiento de datos según 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 la 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	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	Omitir	Active esta opción si desea omitir los errores de formato para el formato de datos JSON.

Nota

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

Opcionalmente, en Configuración avanzada, puede especificar el tipo de identidad administrada que usa la conexión de datos. De forma predeterminada, se selecciona Asignado por el sistema .

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

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

Seleccione Crear

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

Elegir destino para enrutar eventos a

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

Creación de una conexión de datos

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 de Event Grid, un espacio de nombres de Event Hubs y event Hubs automáticamente. De lo contrario, debe 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.

Opcionalmente, 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. A medida que se inicia el patrón aplicado, 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: .
  - 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: .
- 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 más información sobre el filtrado de eventos, consulte Eventos de Blob Storage.

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 la 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	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	Omitir	Active esta opción si desea omitir errores de formato para el formato de datos JSON.

Nota

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

Opcionalmente, en Configuración avanzada, puede especificar el tipo de identidad administrada que usa la conexión de datos. De forma predeterminada, se selecciona Asignado por el sistema .

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

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

Seleccione Crear.

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')]"
            }
        }
    ]
}

Uso de la conexión de datos de Event Grid

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

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

Azure Blob Storage
Azure Data Lake

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.

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 Close parámetro trueen . Este parámetro hace que el método upload desencadene un evento FlushAndClose , lo que indica que se ha realizado la actualización final y se cierra la secuencia de archivos.
Para reducir el tráfico procedente de Event Grid y optimizar la ingesta de eventos en Azure Data Explorer, se recomienda filtrar la clave 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 cuyo nombre ha cambiado el nombre del blob ni inicia la ingesta de blobs incluidos en el directorio. Si desea asegurarse de que la ingesta de blobs después de cambiar el nombre de un directorio, debe 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 CopyBlob operación para las cuentas de almacenamiento que tienen habilitada la característica de espacio de nombres jerárquico en ellas.

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

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

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.
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.
En la barra de menús superior, seleccione Eliminar.

Procesamiento de datos desde el centro de eventos mediante Azure Stream Analytics

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

Requisitos previos

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

Elegir destino para enrutar eventos a

Creación de una conexión de datos

Uso de la conexión de datos de Event Grid

Cambio del nombre de los blobs

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

Comentarios

Comentarios

Recursos adicionales

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

Requisitos previos

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

Uso de la conexión de datos de Event Grid

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

Contenido relacionado

Comentarios

Comentarios

Recursos adicionales