Envío de datos a Azure Data Explorer desde una canalización de Azure IoT Data Processor (versión preliminar)

Importante

Operaciones de IoT de Azure, habilitado por Azure Arc, está actualmente en VERSIÓN PRELIMINAR. No se debería usar este software en versión preliminar en entornos de producción.

Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

Use el destino Azure Data Explorer para escribir datos en una tabla de Azure Data Explorer desde una canalización de Azure IoT Data Processor (versión preliminar). La fase de destino agrupa los mensajes antes de enviarlos a Azure Data Explorer.

Requisitos previos

Para configurar y usar una fase de canalización de destino de Azure Data Explorer, necesita:

• Instancia implementada del procesador de datos.
• Un Clúster de Azure Data Explorer.
• Una base de datos en el clúster de Azure Data Explorer.

Configuración de Azure Data Explorer

Para poder escribir en Azure Data Explorer desde una canalización de datos, debe conceder acceso a la base de datos desde la canalización. Puede usar una entidad de servicio o una identidad administrada para autenticar la canalización en la base de datos. La ventaja de usar una identidad administrada es que no es necesario administrar el ciclo de vida de la entidad de servicio. Azure administra automáticamente la identidad administrada, que se asocia al ciclo de vida del recurso al que está asignada.

Entidad de servicio

Para crear una entidad de servicio con un secreto de cliente:

1. Use el siguiente comando de la CLI de Azure para crear una entidad de servicio.

   az ad sp create-for-rbac --name <YOUR_SP_NAME> 
   

2. La salida de este comando incluye un appId, displayName, password, y tenant. Anote estos valores para usarlos al configurar el acceso al recurso en la nube, como Microsoft Fabric, crear un secreto y configurar un destino de canalización:

   {
       "appId": "<app-id>",
       "displayName": "<name>",
       "password": "<client-secret>",
       "tenant": "<tenant-id>"
   }
   

Para conceder acceso de administrador a la base de datos de Azure Data Explorer, ejecute el siguiente comando en la pestaña consulta de la base de datos:

.add database <DatabaseName> admins (<ApplicationId>) <Notes>

Para que la fase de destino se conecte a Azure Data Explorer, necesita acceso a un secreto que contenga los detalles de autenticación. Para crear un secreto:

1. Use el comando siguiente para agregar un secreto a Azure Key Vault que contiene el secreto de cliente que anotó al crear la entidad de servicio:

   az keyvault secret set --vault-name <your-key-vault-name> --name AccessADXSecret --value <client-secret>
   

2. Agregue la referencia secreta al clúster de Kubernetes siguiendo los pasos descritos en Administración de secretos para la implementación de Operaciones de IoT de Azure (versión preliminar).

Identidad administrada

Para encontrar el identificador de aplicación de la identidad administrada y el identificador de inquilino, ejecute los siguientes comandos. Reemplace los marcadores de posición por el nombre del clúster, el grupo de recursos y el identificador de la suscripción:

CLUSTER_NAME=<Your connected cluster name>
RESOURCE_GROUP=<The resource group where your connected cluster is installed>
SUBSCRIPTION=<The subscription where your connected cluster is installed>
EXTENSION_NAME=processor

OBJECT_ID=$(az k8s-extension show --name $EXTENSION_NAME --cluster-name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --cluster-type connectedClusters --query identity.principalId -o tsv --subscription $SUBSCRIPTION)
echo "App ID:    " `az ad sp show --query appId --id $OBJECT_ID -o tsv`
echo "Tenant ID: " `az account show --query tenantId -o tsv`

Tome nota de los valores App ID y Tenant ID, ya que los necesitará más adelante.

Para agregar la identidad administrada a la base de datos, vaya al portal de Azure Data Explorer y ejecute la siguiente consulta en la base de datos. Reemplace los marcadores de posición por los valores que anotó en el paso anterior:

.add database ['<your-database-name>'] admins ('aadapp=<your-app-ID>;<your-tenant-ID>');

Procesamiento por lotes

El procesador de datos escribe en Azure Data Explorer en lotes. Mientras se procesan los datos por lotes en el procesador de datos antes de enviarlos, Azure Data Explorer tiene su propia directiva de procesamiento por lotes de ingesta predeterminada. Por lo tanto, es posible que no vea los datos en Azure Data Explorer inmediatamente después de que el procesador de datos lo escriba en el destino de Azure Data Explorer.

Para ver los datos en Azure Data Explorer tan pronto como la canalización los envíe, puede establecer el recuento de la directiva de procesamiento por lotes de ingesta en 1. Para editar la directiva de procesamiento por lotes de ingesta, ejecute el siguiente comando en la pestaña consulta de base de datos:

.alter database <your-database-name> policy ingestionbatching
```
{
    "MaximumBatchingTimeSpan" : "00:00:30",
    "MaximumNumberOfItems" : 1,
    "MaximumRawDataSizeMB": 1024
}
```

Configuración de la fase de destino

La configuración JSON de la fase de destino de Azure Data Explorer define los detalles de la fase. Para crear la fase, puede interactuar con la interfaz de usuario basada en formularios o proporcionar la configuración JSON en la pestaña Avanzado :

Campo	Tipo	Descripción	Necesario	Valor predeterminado	Ejemplo
Nombre para mostrar	String	Un nombre para mostrar en la interfaz de usuario del procesador de datos.	Sí	-	Azure IoT MQ output
Descripción	String	Una descripción sencilla de lo que hace la fase.	No		Write to topic default/topic1
Dirección URL del clúster	String	El URI (este valor no es el URI de ingesta de datos).	Sí	-
Base de datos	String	Nombre de la base de datos.	Sí	-
Tabla	String	Nombre de la tabla en la que se va a escribir.	Sí	-
Batch	Batch	Cómo procesar datos porlotes.	No	60s	10s
Volver a intentar	Reintentar	Directiva de reintento que se va a usar.	No	default	fixed
Autenticación1	Cadena	Detalles de autenticación para conectarse a Azure Data Explorer. Service principal o Managed identity	Entidad de servicio	Sí	-
Nombre de columnas >	cadena	El nombre de la columna.	Sí		temperature
Ruta de acceso de columnas >	Path	Ubicación dentro de cada registro de los datos desde los que se debe leer el valor de la columna.	No	.{{name}}	.temperature

¹Autenticación: actualmente, la fase de destino admite la autenticación basada en entidades de servicio o la identidad administrada cuando se conecta a Azure Data Explorer.

Para configurar la autenticación basada en la entidad de servicio, proporcione los valores siguientes. Ha anotado estos valores al crear la entidad de servicio y agregar la referencia secreta a su clúster.

Campo	Descripción	Obligatorio
TenantId	Id. del inquilino.	Sí
ClientId	El identificador de aplicación que anotó al crear la entidad de servicio que tiene acceso a la base de datos.	Sí
Secreto	Referencia secreta que ha creado en el clúster.	Sí

Configuración de ejemplo

En el ejemplo JSON siguiente se muestra una configuración completa de la fase de destino de Azure Data Explorer que escribe todo el mensaje en la tabla quickstart de la base de datos:

{
    "displayName": "Azure data explorer - 71c308",
    "type": "output/dataexplorer@v1",
    "viewOptions": {
        "position": {
            "x": 0,
            "y": 784
        }
    },
    "clusterUrl": "https://clusterurl.region.kusto.windows.net",
    "database": "databaseName",
    "table": "quickstart",
    "authentication": {
        "type": "servicePrincipal",
        "tenantId": "tenantId",
        "clientId": "clientId",
        "clientSecret": "secretReference"
    },
    "batch": {
        "time": "5s",
        "path": ".payload"
    },
    "columns": [
        {
            "name": "Timestamp",
            "path": ".Timestamp"
        },
        {
            "name": "AssetName",
            "path": ".assetName"
        },
        {
            "name": "Customer",
            "path": ".Customer"
        },
        {
            "name": "Batch",
            "path": ".Batch"
        },
        {
            "name": "CurrentTemperature",
            "path": ".CurrentTemperature"
        },
        {
            "name": "LastKnownTemperature",
            "path": ".LastKnownTemperature"
        },
        {
            "name": "Pressure",
            "path": ".Pressure"
        },
        {
            "name": "IsSpare",
            "path": ".IsSpare"
        }
    ],
    "retry": {
        "type": "fixed",
        "interval": "20s",
        "maxRetries": 4
    }
}

La configuración define que:

• Los mensajes se procesan por lotes durante 5 segundos.
• Usa la ruta de acceso.payload del lote para buscar los datos de las columnas.

Ejemplo

En el ejemplo siguiente se muestra un mensaje de entrada de ejemplo a la fase de destino de Azure Data Explorer:

{
  "payload": {
    "Batch": 102,
    "CurrentTemperature": 7109,
    "Customer": "Contoso",
    "Equipment": "Boiler",
    "IsSpare": true,
    "LastKnownTemperature": 7109,
    "Location": "Seattle",
    "Pressure": 7109,
    "Timestamp": "2023-08-10T00:54:58.6572007Z",
    "assetName": "oven"
  },
  "qos": 0,
  "systemProperties": {
    "partitionId": 0,
    "partitionKey": "quickstart",
    "timestamp": "2023-11-06T23:42:51.004Z"
  },
  "topic": "quickstart"
}

Contenido relacionado

• Enviar datos a Microsoft Fabric
• Envío de datos a Azure Blob Storage
• Envío de datos a un punto de conexión gRPC
• Envío de datos a un punto de conexión HTTP
• Publicación de datos en un agente MQTT
• Envío de datos al almacén de datos de referencia