Tarea de Azure DevOps para Azure Data Explorer

Artículo
03/21/2023

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. Esta extensión incluye tres tareas básicas:

Comando de Azure Data Explorer: ejecuta comandos de administración en un clúster de Azure Data Explorer.
Consulta de Azure Data Explorer: ejecuta consultas en un clúster de Azure Data Explorer y analiza los resultados.
Puerta del servidor de consultas de Azure Data Explorer: tarea sin agente para canalizar versiones según el resultado de la consulta.

En este documento se describe un ejemplo sencillo de uso de la tarea Azure Data Explorer: Herramientas de canalización para implementar los 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 una 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 Microsoft Entra aplicación mediante el aprovisionamiento de una aplicación de Microsoft Entra.
- Conceda acceso a la aplicación de Microsoft Entra en la base de datos de Azure Data Explorer mediante la administración de permisos de 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.
- Si NO es el propietario de la instancia de Azure DevOps, póngase en contacto con el propietario y pídale que la instale.

Preparación del contenido para la publicación

Hay tres maneras de ejecutar comandos de administración en el clúster de una tarea.

Opciones de control de código fuente del comando.

Usar 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)
Escribir comandos insertados
Especificar una ruta de acceso a los archivos para obtener los 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 de aquí en las carpetas respectivas, como se muestra a continuación, 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 que haga su código idempotente. Por ejemplo, utilice .create-merge table en lugar de .create table y utilice la función .create-or-alter en lugar de la función .create.

Creación de una canalización de versión

Inicie sesión en su organización de Azure DevOps.
Seleccione Canalizaciones>Versiones en el menú izquierdo y elija Nueva canalización.
Se abrirá la ventana Nueva canalización de versión. En la pestaña Canalizaciones, en el panel Seleccionar una plantilla, elija Empty job (Trabajo vacío).
Seleccione el botón Fase. En el panel Fase, agregue el valor de Nombre de la fase. 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 haga clic en Agregar. Seleccione Guardar para guardar la canalización.
En la pestaña Variables, seleccione + Agregar para crear una variable para Dirección URL de extremo que se usará en la tarea. Escriba los valores de Nombre y Valor del punto de conexión. Seleccione Guardar para guardar la canalización.

Para buscar su Endpoint_URL, la página de información general del clúster de Azure Data Explorer en Azure Portal contiene el URI del clúster de Azure Data Explorer. Cree el URI con el siguiente formato https://<Azure Data Explorer cluster URI>?DatabaseName=<DBName>. Por ejemplo: https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

Creación de tareas para implementar las carpetas

En la pestaña Canalización, haga clic en 1 job, 0 task (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:

Adición de comandos de administrador.

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
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 entidad de servicio	Escriba el identificador de aplicación de Microsoft Entra (creado como requisito previo)
Service Principal App Key (Clave de la aplicación de entidad de servicio)	Escriba la clave de aplicación Microsoft Entra (creada como requisito previo).
id. de inquilino de Microsoft Entra	Escriba el inquilino 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.

Agregar una conexión de servicio.

Seleccione Guardar y, a continuación, en la pestaña Tareas compruebe que hay tres tareas: Implementación de tablas, Implementación de funciones e Implementación de 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 una canalización de compilación o versión se puede usar para validar un conjunto de datos y tener un paso correcto o un error 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, Consulta del clúster.
- Tipo: seleccione Insertada.
- 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.

Creación de una tarea de puerta del servidor de consultas

Si es necesario, cree una tarea para ejecutar una consulta en un clúster y obtenga el número de filas de los resultados de consulta pendientes. 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 para mostrar: 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 Inline query (Consulta insertada).
- 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.

Tarea de puerta de consulta.

Ejecución de la versión

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

Ahora ha completado la creación de una canalización de versión para la implementación en preproducción.

Configuración de la canalización de Yaml

Las tareas se pueden configurar a través de la interfaz de usuario web de Azure DevOps (como se ha mostrado anteriormente) y a través del código Yaml dentro del esquema de canalización.

Uso de ejemplo de comandos de administrador

steps:
- task: Azure-Kusto.PublishToADX.PublishToADX.PublishToADX@1
  displayName: '<Task Name>'
  inputs:
    script: '<inline Script>'
    waitForOperation: true
    kustoUrls: '$(CONNECTIONSTRING):443?DatabaseName=""'
    customAuth: true
    connectedServiceName: '<Service Endpoint Name>'
    serialDelay: 1000
  continueOnError: true
  condition: ne(variables['ProductVersion'], '') ## Custom condition Sample

Uso del ejemplo de consulta

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@1
  displayName: '<Task Display Name>'
  inputs:
    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=<DataBaneName>'
    customAuth: true
    connectedServiceName: '<Service Endpoint Name>'
  continueOnError: true