Tarea de Azure DevOps para Azure Data Explorer

Azure DevOps Services proporciona herramientas de colaboración para el desarrollo, como canalizaciones de alto rendimiento, repositorios de Git privados gratuitos, paneles Kanban configurables y amplias capacidades de pruebas automatizadas y continuas. Azure Pipelines es una capacidad de Azure DevOps que permite administrar CI/CD para implementar el código con las canalizaciones de alto rendimiento que funcionan con cualquier lenguaje, plataforma y nube. Azure Data Explorer: Herramientas de canalización es la tarea de Azure Pipelines que le permite crear canalizaciones de versión e implementar cambios en sus bases de datos de Azure Data Explorer. Está disponible de forma gratuita en Visual Studio Marketplace. La extensión incluye las siguientes tareas básicas:

Comando de Azure Data Explorer: ejecución de comandos de administrador en un clúster de Azure Data Explorer
Consulta de Azure Data Explorer: ejecución de consultas en un clúster de Azure Data Explorer y análisis de los resultados
Puerta del servidor de consultas de Azure Data Explorer: tarea sin agente para controlar las publicaciones según el resultado de la consulta

En este documento se describe un ejemplo sencillo del uso de la tarea Herramientas de canalización de Azure Data Explorer para implementar cambios de esquema en la base de datos. Para obtener información sobre las canalizaciones de CI/CD completas, consulte la documentación de Azure DevOps.

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.
Configuración del clúster de Azure Data Explorer:
- Cree una aplicación de Microsoft Entra mediante el aprovisionamiento de una aplicación de Microsoft Entra.
- Conceda acceso a su aplicación Microsoft Entra en la base de datos de Azure Data Explorer gestionando los permisos de la base de datos de Azure Data Explorer.
Instalación de Azure DevOps:
Instalación de la extensión:
- Si es el propietario de la instancia de Azure DevOps, instale la extensión desde Marketplace; de lo contrario, póngase en contacto con el propietario de la instancia de Azure DevOps y pídale que la instale.

Preparación del contenido para la publicación

Puede usar los métodos siguientes para ejecutar comandos de administrador en un clúster dentro de una tarea:

Recorte de pantalla que muestra las opciones de control de código fuente del comando.

Use un patrón de búsqueda para obtener varios archivos de comandos de una carpeta del agente local (orígenes de compilación o artefactos de versión). La opción de una sola línea admite varios archivos con un comando por archivo.
Escribir comandos en línea.
Especifique una ruta de acceso de archivo para obtener archivos de comandos directamente desde el control de código fuente de Git (recomendado).

Cree las siguientes carpetas de ejemplo (Funciones, Directivas y Tablas) en el repositorio de Git. Copie los archivos del repositorio de ejemplos en las carpetas respectivas y confirme los cambios. Los archivos de ejemplo se proporcionan para ejecutar el siguiente flujo de trabajo.

Sugerencia

Al crear su propio flujo de trabajo, le recomendamos asegurar que su código sea idempotente. Por ejemplo, use .create-merge table en lugar de .create tabley use la .create-or-alter función en lugar de la .create función .

Crear una pipeline de liberación

Inicie sesión en su organización de Azure DevOps.
Seleccione Lanzamientos de canalizaciones> en el menú izquierdo y, a continuación, seleccione Nueva canalización.
La ventana Nueva canalización de versión se abrirá. En la pestaña Canalizaciones, en el panel Seleccionar una plantilla, elija Empty job (Trabajo vacío).
Seleccione el botón Etapa. En el panel Fase , agregue el nombre de la fase y, a continuación, seleccione Guardar para guardar la canalización.
Seleccione el botón Agregar un artefacto. En el panel Agregar un artefacto, seleccione el repositorio donde existe el código, rellene la información pertinente y seleccione Agregar. Seleccione Guardar para guardar la canalización.
En la pestaña Variables , seleccione + Agregar para crear una variable para la dirección URL del punto de conexión que se usa en la tarea. Escriba el nombre y el valor del punto de conexión y, a continuación, seleccione Guardar para guardar la canalización.

Para buscar la dirección URL del punto de conexión, vaya a la página de información general del clúster de Azure Data Explorer en Azure Portal y copie el URI del clúster. Construya el URI de variable en el formato siguiente https://<ClusterURI>?DatabaseName=<DBName>. Por ejemplo: https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

Crea una tarea para desplegar las carpetas

En la pestaña Canalización, seleccione 1 trabajo, 0 tareas para agregar tareas.

Repita los pasos siguientes para crear tareas de comando para implementar archivos desde las carpetas Tables, Functions y Policies:

Recorte de pantalla que muestra cómo agregar un comando de administrador de Azure Data Explorer.

En la pestaña Tareas, seleccione + al lado de Trabajo de agente y busque Azure Data Explorer.
En Run Azure Data Explorer Command (Ejecutar comando de Azure Data Explorer), seleccione Agregar.

Seleccione Kusto Command (Comando Kusto) y actualice la tarea con la siguiente información:

Nombre para mostrar: nombre de la tarea. Por ejemplo, Deploy <FOLDER> donde <FOLDER> es el nombre de la carpeta de la tarea de implementación que va a crear.
Ruta de acceso del archivo: para cada carpeta, especifique la ruta de acceso como, por ejemplo, */<FOLDER>/*.csl donde <FOLDER> es la carpeta pertinente para la tarea.
Dirección URL del punto de conexión: especifique la variable EndPoint URL creada en el paso anterior.
Use Service Endpoint (Usar punto de conexión de servicio): seleccione esta opción.

Punto de conexión de servicio: seleccione un punto de conexión de servicio existente o cree uno nuevo (+ Nuevo) que proporcione la siguiente información en la ventana Add Azure Data Explorer service connection (Agregar conexión del servicio de Azure Data Explorer):

Configuración	Valor sugerido
Método de autenticación	Configurar Credenciales de Identidad Federada (FIC) (recomendado) o Seleccionar Autenticación de Principal de Servicio (SPA).
Nombre de la conexión	Escriba un nombre para identificar este punto de conexión de servicio.
URL de clúster	El valor se puede encontrar en la sección de información general del clúster de Azure Data Explorer en Azure Portal.
Id. de principal de servicio	Escriba el identificador de aplicación de Microsoft Entra (creado como requisito previo)
Clave de la aplicación del Principal de Servicio	Escriba la clave de aplicación de Microsoft Entra (creada como requisito previo)
Identificador de inquilino de Microsoft Entra	Introduzca el inquilinato de Microsoft Entra (por ejemplo, microsoft.com o contoso.com)

Seleccione la casilla Permita que todas las canalizaciones usen esta conexión y, después, Aceptar.

Recorte de pantalla que muestra cómo agregar una conexión de servicio.

Si tus comandos de administrador son operaciones asincrónicas de larga duración, selecciona la casilla Esperar a que se completen los comandos de administrador asincrónicos de larga duración. Cuando está habilitada, la tarea sondea el estado de la operación utilizando .show operations hasta que se complete el comando.

Seleccione Guardar y, a continuación, en la pestaña Tareas , compruebe que hay tres tareas: Implementar tablas, Implementar funciones e Implementar directivas.

Creación de una tarea de consulta

Si es necesario, cree una tarea para ejecutar una consulta en el clúster. La ejecución de consultas en un pipeline de build o release se puede usar para validar un conjunto de datos y tener un paso exitoso o fallido en función de los resultados de la consulta. Los criterios de éxito de las tareas se pueden basar en un umbral de recuento de filas o un valor único en función de lo que devuelva la consulta.

En la pestaña Tareas, seleccione + al lado de Trabajo de agente y busque Azure Data Explorer.
En Run Azure Data Explorer Query (Ejecutar consulta de Azure Data Explorer), seleccione Agregar.
Seleccione Kusto Query (Consulta de Kusto) y actualice la tarea con la siguiente información:
- Nombre para mostrar: nombre de la tarea. Por ejemplo, Clúster de consulta.
- Tipo: seleccione En línea.
- Consulta: escriba la consulta que desea ejecutar.
- Dirección URL del punto de conexión: especifique la variable EndPoint URL creada anteriormente.
- Use Service Endpoint (Usar punto de conexión de servicio): seleccione esta opción.
- Punto de conexión de servicio: seleccione un punto de conexión de servicio.
En Resultados de la tarea, seleccione los criterios de éxito de la tarea en función de los resultados de la consulta, como se muestra a continuación:
- Si la consulta devuelve filas, seleccione Número de filas y proporcione los criterios que necesita.
- Si la consulta devuelve un valor, seleccione Valor único y proporcione el resultado esperado.

Crear una tarea de puerta de servidor de consultas

Si es necesario, cree una tarea para ejecutar una consulta en un clúster y controlar el progreso de la publicación en espera del recuento de filas de los resultados de la consulta. La tarea de puerta del servidor de consultas es un trabajo sin agente, lo que significa que la consulta se ejecuta directamente en Azure DevOps Server.

En la pestaña Tareas, seleccione + al lado de Trabajo sin agente y busque Azure Data Explorer.
En Run Azure Data Explorer Query Server Gate (Ejecutar puerta del servidor de consultas de Azure Data Explorer), seleccione Agregar.
Seleccione Kusto Query Server Gate (Puerta del servidor de consultas de Kusto) y, a continuación, seleccione Server Gate Test (Prueba de puerta de servidor).
Para configurar la tarea, proporcione la información siguiente:
- Nombre visible: Nombre de la puerta.
- Punto de conexión de servicio: seleccione un punto de conexión de servicio.
- Nombre de la base de datos: especifique el nombre de la base de datos.
- Tipo: seleccione Consulta insertada (Inline query).
- Consulta: escriba la consulta que desea ejecutar.
- Umbral máximo: especifique el número máximo de filas para los criterios de éxito de la consulta.

Nota:

Debería ver unos resultados como los siguientes al ejecutar la versión.

Recorte de pantalla que muestra un ejemplo de resultados de la tarea Puerta de consulta.

Ejecutar la versión

Seleccione + Publicar>Crear publicación para iniciar una publicación.
En la pestaña Registros, compruebe si el estado de implementación es correcto.

Ahora se ha completado la configuración de un pipeline de lanzamiento para la implementación en preproducción.

Compatibilidad con la autenticación sin claves para las tareas de DevOps de Azure Data Explorer

La extensión admite la autenticación sin claves para clústeres de Azure Data Explorer. La autenticación sin claves le permite autenticarse en clústeres de Azure Data Explorer sin usar una clave. Es más seguro y fácil de administrar.

Nota:

Las direcciones URL del clúster de Kusto Fabric no se admiten para la federación de identidades de carga de trabajo (WIF) y la autenticación de identidad administrada.

Uso de la autenticación de credenciales de identidad federada (FIC) en una conexión de servicio de Azure Data Explorer

Nota:

A partir de la versión 4.0.x de la extensión, el punto de conexión de servicio de Azure Data Explorer admite la autenticación de federación de identidades de carga de trabajo (WIF) además de la autenticación de entidad de servicio.

En la instancia de DevOps, vaya a Configuración del proyecto>Conexiones de servicio>Nueva conexión de servicio>Azure Data Explorer.
Seleccione Credenciales de identidad federada, y escriba la dirección URL del clúster, el identificador de entidad de servicio, el identificador de inquilino, un nombre de conexión de servicio y a continuación, seleccione Guardar.
En Azure Portal, abra la aplicación Microsoft Entra para la entidad de servicio especificada.
En Certificados y secretos, seleccione Credenciales federadas.
Seleccione Agregar credencial y después, para Escenario de credenciales federadas, seleccione Otro emisor, y rellene la configuración con la siguiente información:
- Emisor: <https://vstoken.dev.azure.com/{System.CollectionId}> donde {System.CollectionId} es el identificador de colección de la organización de Azure DevOps. Puede encontrar el identificador de colección de las maneras siguientes:
  - En el pipeline de lanzamiento clásico de Azure DevOps, seleccione Inicializar tarea. El identificador de colección se muestra en los registros.
- Identificador del firmante: <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}> donde {DevOps_Org_name} es el nombre de la organización de Azure DevOps, {Project_Name} es el nombre del proyecto y {Service_Connection_Name} es el nombre de la conexión de servicio que creó anteriormente.
  
  Nota:
  
  Si hay un espacio en el nombre de su conexión de servicio, puede usarlo con el espacio en el campo. Por ejemplo: sc://MyOrg/MyProject/My Service Connection.
- Nombre: escriba un nombre para la credencial.
Seleccione Agregar.

Uso de credenciales de identidad federada o identidad administrada en una conexión de servicio de Azure Resource Manager (ARM)

En la instancia de DevOps, vaya a Configuración del proyecto>Conexiones de servicio>Nueva conexión de servicio>Azure Resource Manager.
En Método de autenticación, seleccione Federación de identidad de carga de trabajo (automática) para continuar. También puede usar la opción manual de federación de identidad de la carga de trabajo (manual) para especificar los detalles de la federación de identidad de la carga de trabajo o la opción Identidad administrada. Obtenga más información sobre cómo configurar una identidad administrada mediante Azure Resource Management en conexiones de servicio de Azure Resource Manager (ARM).
Rellene los detalles necesarios, seleccione Comprobar, y a continuación, seleccione Guardar.

Configuración de canalización de YAML

Puede configurar tareas mediante la interfaz de usuario web de Azure DevOps o el código YAML dentro del esquema de canalización.

La extensión proporciona tres tareas de canalización, todas accesibles a través de YAML:

Comando de Azure Data Explorer (ADXAdminCommand@5): ejecución de comandos de administrador/control en un clúster de ADX
Consulta de Azure Data Explorer : ejecución de consultas en un clúster de ADX y análisis de los resultados
Puerta del servidor de consultas de Azure Data Explorer — tarea sin agente para controlar las versiones dependiendo del resultado de la consulta

Sugerencia

Para mejorar la seguridad, utilice la Federación de identidad de cargas de trabajo o la autenticación de Identidad Administrada a través de una conexión de servicio de Azure Resource Manager en lugar de almacenar credenciales directamente en su canalización. Estos métodos de autenticación sin claves son el procedimiento recomendado.

Ejemplo de comando de administrador — comandos en línea

En el ejemplo siguiente se ejecuta un comando de administrador insertado mediante una conexión de servicio de Azure Resource Manager (ARM), que admite la federación de identidades de carga de trabajo (WIF) y la autenticación de identidad administrada:

steps:
- task: Azure-Kusto.ADXAdminCommands.PublishToADX.ADXAdminCommand@5
  displayName: 'Run inline ADX admin command'
  inputs:
    clusterUri: 'https://<ClusterName>.<Region>.kusto.windows.net'
    databaseName: '<DatabaseName>'
    commandsSource: 'inline'
    inlineCommands: |
      .create-merge table MyTable (Id:int, Name:string, Timestamp:datetime)
      .create-or-alter function MyFunction() { MyTable | take 10 }
    azureSubscription: '<ARM Service Connection Name>'
  continueOnError: true

Ejemplo de comando de administrador: comandos basados en archivos

En el ejemplo siguiente se ejecutan comandos de administrador de archivos que coinciden con un patrón global, mediante la autenticación de registro de aplicaciones de AAD:

steps:
- task: Azure-Kusto.ADXAdminCommands.PublishToADX.ADXAdminCommand@5
  displayName: 'Deploy schema from files'
  inputs:
    clusterUri: 'https://<ClusterName>.<Region>.kusto.windows.net'
    databaseName: '<DatabaseName>'
    commandsSource: 'files'
    commandFilesPattern: '**/*.csl'
    aadAppId: '$(AAD_APP_ID)'
    aadAppKey: '$(AAD_APP_KEY)'
    aadTenantId: '$(AAD_TENANT_ID)'
  continueOnError: true

También puede usar **/*.kql como patrón global en función de la convención de nomenclatura de archivos.

Ejemplo de comando de administración: conexión de servicio de Azure Resource Manager

En el ejemplo siguiente se usa una conexión de servicio de Azure Resource Manager, que admite la federación de identidades de carga de trabajo (WIF) e identidad administrada para la autenticación sin claves:

steps:
- task: Azure-Kusto.ADXAdminCommands.PublishToADX.ADXAdminCommand@5
  displayName: 'Deploy schema via ARM service connection'
  inputs:
    clusterUri: 'https://<ClusterName>.<Region>.kusto.windows.net'
    databaseName: '<DatabaseName>'
    commandsSource: 'files'
    commandFilesPattern: '**/*.csl'
    azureSubscription: '<ARM Service Connection Name>'
  continueOnError: true
  condition: ne(variables['ProductVersion'], '')

Parámetros de entrada de tareas

En la tabla siguiente se describen los parámetros de entrada clave de la ADXAdminCommand@5 tarea:

Parámetro	Descripción
`clusterUri`	URI base para el clúster de Kusto (por ejemplo, `https://<ClusterName>.<Region>.kusto.windows.net`)
`databaseName`	El nombre de la base de datos de destino
`commandsSource`	El origen de los comandos: `inline` para los comandos KQL insertados o `files` para los comandos basados en archivos
`inlineCommands`	Comandos KQL en línea para ejecutar (se utilizan cuando `commandsSource` es `inline`)
`commandFilesPattern`	Patrón Glob para archivos de script (se usa cuando `commandsSource` es `files`), por ejemplo `*/.csl` o `*/.kql`
`aadAppId`	Identificador de la aplicación de Microsoft Entra (Principal de Servicio) para la autenticación de la aplicación de AAD
`aadAppKey`	La clave y el secreto de la aplicación de Microsoft Entra para la autenticación de aplicaciones de AAD
`aadTenantId`	Identificador de inquilino de Microsoft Entra para la autenticación de aplicaciones de AAD
`azureSubscription`	Nombre de la conexión de servicio de Azure Resource Manager para la autenticación basada en ARM (admite WIF e identidad administrada).

Métodos de autenticación

La extensión admite los siguientes métodos de autenticación:

Registro de aplicaciones de Azure Active Directory (AAD): use aadAppId, aadAppKey y aadTenantId para autenticarse con una entidad de servicio. Almacene las credenciales como variables de canalización seguras.
Autenticación basada en certificados — Utilice un certificado en lugar de una clave de aplicación para autenticar el Principal del Servicio. Almacene los detalles del certificado como variables de canalización seguras.
Identidad administrada : use una conexión de servicio de Azure Resource Manager configurada con identidad administrada. Establezca la azureSubscription entrada en el nombre de la conexión de servicio.
Federación de identidades de carga de trabajo (WIF): use una conexión de servicio de Azure Resource Manager con la federación de identidades de carga de trabajo (automática o manual). Este es el enfoque sin clave recomendado. Establezca la azureSubscription entrada como nombre de la conexión de servicio.

Nota:

La Workload Identity Federation (WIF) es una incorporación más reciente a la extensión. Habilita la autenticación sin secretos y es el enfoque recomendado para las nuevas canalizaciones. Para obtener instrucciones de configuración, consulte Uso de credenciales de identidad federada o identidad administrada en una conexión de servicio de Azure Resource Manager (ARM).

Ejemplo de consulta

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@5
  displayName: '<Task Display Name>'
  inputs:
    targetType: 'inline'
    script: |
     let badVer=
     RunnersLogs | where Timestamp > ago(30m)
         | where EventText startswith "$$runnerresult" and Source has "ShowDiagnostics"
         | extend State = extract(@"Status='(.*)', Duration.*",1, EventText)
         | where State == "Unhealthy"
         | extend Reason = extract(@'"NotHealthyReason":"(.*)","IsAttentionRequired.*',1, EventText)
         | extend Cluster = extract(@'Kusto.(Engine|DM|CM|ArmResourceProvider).(.*).ShowDiagnostics',2, Source)
         | where Reason != "Merge success rate past 60min is < 90%"
         | where Reason != "Ingestion success rate past 5min is < 90%"
         | where Reason != "Ingestion success rate past 5min is < 90%, Merge success rate past 60min is < 90%"
         | where isnotempty(Cluster)
         | summarize max(Timestamp) by Cluster,Reason
         | order by  max_Timestamp desc
         | where Reason startswith "Differe"
         | summarize by Cluster
     ;
      DimClusters | where Cluster in (badVer)
     | summarize by Cluster , CmConnectionString , ServiceConnectionString ,DeploymentRing
     | extend ServiceConnectionString = strcat("#connect ", ServiceConnectionString)
     | where DeploymentRing == "$(DeploymentRing)"
    kustoUrls: 'https://<ClusterName>.kusto.windows.net?DatabaseName=<DatabaseName>'
    authType: 'kustoserviceconn'
    connectedServiceName: '<connection service name>'
    minThreshold: '0'
    maxThreshold: '10'
  continueOnError: true

Comentarios

Resultoulle útil esta páxina?

Last updated on 2026-03-25

Compartir por

Tarea de Azure DevOps para Azure Data Explorer

Requisitos previos

Preparación del contenido para la publicación

Crear una pipeline de liberación

Crea una tarea para desplegar las carpetas

Creación de una tarea de consulta

Crear una tarea de puerta de servidor de consultas

Ejecutar la versión

Compatibilidad con la autenticación sin claves para las tareas de DevOps de Azure Data Explorer

Uso de la autenticación de credenciales de identidad federada (FIC) en una conexión de servicio de Azure Data Explorer

Uso de credenciales de identidad federada o identidad administrada en una conexión de servicio de Azure Resource Manager (ARM)

Configuración de canalización de YAML

Ejemplo de comando de administrador — comandos en línea

Ejemplo de comando de administrador: comandos basados en archivos

Ejemplo de comando de administración: conexión de servicio de Azure Resource Manager

Parámetros de entrada de tareas

Métodos de autenticación

Ejemplo de consulta

Comentarios

Recursos adicionais