Compartir a través de

Solución de problemas de CI/CD, Azure DevOps y GitHub en Azure Data Factory y Synapse Analytics

SE APLICA A: Azure Data Factory Azure Synapse Analytics

Sugerencia

Pruebe Data Factory en Microsoft Fabric, una solución de análisis todo en uno para empresas. Microsoft Fabric abarca todo, desde el movimiento de datos hasta la ciencia de datos, el análisis en tiempo real, la inteligencia empresarial y los informes. ¡Obtenga más información sobre cómo iniciar una nueva evaluación gratuita!

En este artículo vamos a explorar métodos habituales de solución de problemas de integración continua/implementación continua (CI/CD), Azure DevOps y GitHub en Azure Data Factory y Synapse Analytics.

Si tiene preguntas o problemas en relación con el uso de las técnicas de DevOps o el control de código fuente, aquí encontrará algunos artículos que pueden resultarle útiles:

  • Consulte Control de código fuente para información sobre cómo se lleva a cabo el control de código fuente en el servicio.
  • Vea CI/CD para más información sobre cómo se lleva a cabo la integración continua/implementación continua de DevOps en el servicio.

Errores habituales y mensajes

Error de conexión al repositorio de Git debido a un inquilino distinto

Incidencia

A veces se producen problemas de autenticación, como el estado HTTP 401. Esto ocurre especialmente cuando tiene varios inquilinos con una cuenta de invitado, lo que puede complicar las cosas.

Causa

El token se ha obtenido del inquilino original, pero el servicio está en el inquilino invitado intentando usar el token para visitar DevOps en el inquilino invitado. Este tipo de acceso de token no es el comportamiento esperado.

Recomendación

Debe usar el token emitido desde el inquilino invitado. Por ejemplo, tiene que asignar el mismo Microsoft Entra ID a su inquilino invitado y a su DevOps, para que pueda establecer correctamente el comportamiento del token y utilizar el inquilino correcto.

Los parámetros de plantilla del archivo de parámetros no son válidos

Incidencia

Si eliminamos un desencadenador en la rama de desarrollo, que ya está disponible en la rama de prueba o de producción con la misma configuración (por ejemplo, la frecuencia y el intervalo), la implementación de la canalización de versión se realiza correctamente y el desencadenador correspondiente se elimina en los entornos respectivos. Sin embargo, si tiene diferentes configuraciones (como la frecuencia y el intervalo) para el desencadenador en los entornos de prueba o producción y elimina el mismo desencadenador en el entorno de desarrollo, se produce un error en la implementación.

Causa

Error de la canalización de CI/CD:

2020-07-20T11:19:02.1276769Z ##[error]Deployment template validation failed: 'The template parameters 'Trigger_Salesforce_properties_typeProperties_recurrence_frequency, Trigger_Salesforce_properties_typeProperties_recurrence_interval, Trigger_Salesforce_properties_typeProperties_recurrence_startTime, Trigger_Salesforce_properties_typeProperties_recurrence_timeZone' in the parameters file are not valid; they are not present in the original template and can therefore not be provided at deployment time. The only supported parameters for this template are 'factoryName, PlanonDWH_connectionString, PlanonKeyVault_properties_typeProperties_baseUrl

Recomendación

Este error se produce porque a menudo se elimina un desencadenador que está parametrizado, por lo que los parámetros no estarán disponibles en la plantilla de Azure Resource Manager (ARM) (dado que el desencadenador ya no existe). Dado que el parámetro ya no está en la plantilla de ARM, es necesario actualizar los parámetros invalidados en la canalización de DevOps. De lo contrario, cada vez que cambian los parámetros de la plantilla de ARM, deben actualizar los parámetros invalidados en la canalización de DevOps (en la tarea de implementación).

No se admite la actualización del tipo de propiedad

Incidencia

Error de la canalización de versión de CI/CD:

2020-07-06T09:50:50.8716614Z There were errors in your deployment. Error code: DeploymentFailed.
2020-07-06T09:50:50.8760242Z ##[error]At least one resource deployment operation failed. Please list deployment operations for details. Please see https://aka.ms/DeployOperations for usage details.
2020-07-06T09:50:50.8771655Z ##[error]Details:
2020-07-06T09:50:50.8772837Z ##[error]DataFactoryPropertyUpdateNotSupported: Updating property type is not supported.
2020-07-06T09:50:50.8774148Z ##[error]DataFactoryPropertyUpdateNotSupported: Updating property type is not supported.
2020-07-06T09:50:50.8775530Z ##[error]Check out the troubleshooting guide to see if your issue is addressed: https://learn.microsoft.com/azure/devops/pipelines/tasks/deploy/azure-resource-group-deployment#troubleshooting
2020-07-06T09:50:50.8776801Z ##[error]Task failed while creating or updating the template deployment.

Causa

Este error se debe a que en la instancia de servicio de destino hay un entorno de ejecución de integración con el mismo nombre, pero de un tipo distinto. El entorno de ejecución de integración debe ser del mismo tipo durante la implementación.

Recomendación

  • Tenga en cuenta los procedimientos recomendados para CI/CD.

  • Los entornos de ejecución de integración no cambian a menudo y son similares en todas las fases de CI/CD, por lo que el servicio espera el mismo nombre y el mismo tipo de entorno de ejecución de integración en todas las fases de CI/CD. Si el nombre y los tipos y propiedades son diferentes, asegúrese de que las configuraciones del entorno de ejecución de integración de origen y de destino sean iguales y, a continuación, implemente la canalización de versión.

  • Si quiere compartir entornos de ejecución de integración en todas las fases, considere la posibilidad de usar una factoría ternaria solo para contener los entornos de ejecución de integración compartidos. Puede usar esta factoría compartida en todos los entornos como un tipo de entorno de ejecución de integración vinculado.

Error al crear o actualizar documentos debido a una referencia no válida

Incidencia

Al intentar publicar cambios, aparece el mensaje de error siguiente:

"error": { "code": "BadRequest", "message": "The document creation or update failed because of invalid reference '<entity>'.", "target": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/<rgname>/providers/Microsoft.DataFactory/factories/<datafactory>/pipelines/<pipeline>", "details": null }

Causa

Ha desasociado la configuración de Git y la ha configurado de nuevo con la marca "Importar recursos" seleccionada, que establece el servicio como "Sincronizado". Esto significa que no hay ningún cambio durante la publicación.

Resolución

Desasocie la configuración de Git y vuelva a configurarla, asegurándose de NO activar la casilla de importar recursos existentes.

No se puede mover una instancia de Data Factory de un grupo de recursos a otro

Incidencia

No se puede trasladar una instancia de Data Factory de un grupo de recursos a otro y se recibe el siguiente error: { "code": "ResourceMoveProviderValidationFailed", "message": "Resource move validation failed. Please see details. Diagnostic information: timestamp 'xxxxxxxxxxxxZ', subscription id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', tracking id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', request correlation id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.", "details": [ { "code": "BadRequest", "target": "Microsoft.DataFactory/factories", "message": "One of the resources contain integration runtimes that are either SSIS-IRs in starting/started/stopping state, or Self-Hosted IRs which are shared with other resources. Resource move is not supported for those resources." } ] }

Resolución

Puede eliminar el entorno de ejecución de integración de SSIS y el entorno de ejecución de integración compartido para permitir la operación de traslado. Si no quiere eliminar los entornos de ejecución de integración, lo mejor es seguir el documento de copia y clonación para realizar una copia y, después, eliminar la antigua instancia de Data Factory.

No se puede exportar ni importar la plantilla de ARM

Incidencia

No es posible exportar ni importar la plantilla de ARM. No se ha producido ningún error en el portal; sin embargo, en el seguimiento del explorador, puede ver el siguiente error:

Failed to load resource: the server responded with a status code of 401 (Unauthorized)

Causa

Ha creado un rol personalizado como usuario y no tenía el permiso necesario. Cuando se carga la interfaz de usuario, se comprueba una serie de valores de control de exposición. En este caso, el rol de acceso del usuario no tiene permiso para acceder a la API queryFeaturesValue. Para acceder a esta API, la característica de parámetros globales se desactiva. La ruta de acceso al código de exportación de la plantilla de ARM se basa en parte en la característica de parámetros globales.

Resolución

Para resolver el problema, debe agregar el siguiente permiso al rol: Microsoft.DataFactory/factories/queryFeaturesValue/action. Este permiso se incluye de forma predeterminada en el rol Colaborador de Data Factory para Data Factory y el rol Colaborador en Synapse Analytics.

No se puede automatizar la publicación de CI/CD

Causa

Hasta hace poco, solo era posible publicar una canalización para las implementaciones haciendo clic en la interfaz de usuario en el portal. Ahora, este proceso se puede automatizar.

Resolución

Se ha mejorado el proceso de CI/CD. La característica de publicación de tipo Automatizado toma, valida y exporta todas las características de plantilla de ARM de la interfaz de usuario. Hace que la lógica se consuma mediante un paquete npm disponible públicamente @microsoft/azure-data-factory-utilities. Este método le permite desencadenar mediante programación estas acciones en lugar de tener que ir a la interfaz de usuario y hacer clic en un botón. Este método proporciona a las canalizaciones de CI/CD una verdadera experiencia de integración continua. Siga las Mejoras de publicación de CI/CD para obtener los detalles.

No se puede publicar debido a un límite de la plantilla de ARM de 4 MB

Incidencia

No puede realizar la implementación porque se alcanzó el límite de tamaño total de 4 MB de la plantilla de Azure Resource Manager. Necesita una solución para implementar después de rebasar el límite.

Causa

Azure Resource Manager restringe el tamaño de la plantilla a 4 MB. Limite el tamaño de la plantilla a 4 MB y cada archivo de parámetros a 64 KB. El límite de 4 MB se aplica al estado final de la plantilla una vez se ha ampliado con definiciones de recursos iterativas y los valores de variables y parámetros. Sin embargo, ha superado el límite.

Resolución

En el caso de soluciones pequeñas o medianas, es más fácil entender y mantener una única plantilla. Puede ver todos los recursos y valores en un único archivo. Para los escenarios avanzados, las plantillas vinculadas le permiten desglosar la solución en componentes dirigidos. Siga los procedimientos recomendados en Uso de plantillas vinculadas y anidadas.

El límite de 20 MB de la API de DevOps hace que ADF se desencadene dos veces o más en lugar de una.

Incidencia

Al publicar recursos, la canalización de Azure se desencadena dos veces o más en lugar de una.

Causa

Azure DevOps tiene el límite de API de REST, que es de 20 MB. Cuando la plantilla de ARM supera este tamaño, ADF divide internamente el archivo de plantilla en varios archivos con plantillas vinculadas para resolver este problema. Como efecto secundario, esta división podría dar lugar a que los desencadenadores del cliente se ejecuten más de una vez.

Resolución

Use la publicación automatizada de ADF (preferida) o el método de desencadenador manual para desencadenar una vez en lugar de dos veces o más.

No se puede establecer la conexión a GIT Enterprise

Incidencia

No se puede conectar a GIT Enterprise debido a problemas de permisos. Puede ver un error como 422 - Entidad no procesable.

Causa

  • No ha configurado OAuth para el servicio.
  • La dirección URL está mal configurada. El valor RepoConfiguration debe ser de tipo FactoryGitHubConfiguration.

Resolución

Conceda acceso de OAuth a al servicio al principio. Después, tiene que usar la dirección URL correcta para conectarse a GIT Enterprise. La configuración debe establecerse en las organizaciones del cliente. Por ejemplo, el servicio prueba primero las https://hostname/api/v3/search/repositories?q=user%3<credenciales del cliente>.... y se producen errores. A continuación, prueba https://hostname/api/v3/orgs/<org>/<repo>... y la operación se realiza correctamente.

No es posible la recuperación desde una instancia eliminada

Incidencia

Se eliminó una instancia del servicio o el grupo de recursos que la contiene y es necesario recuperarla.

Causa

Solo es posible recuperar la instancia si se configuró el control de código fuente para hacerlo con DevOps o Git. Esta acción proporciona todos los recursos publicados más recientes, pero no restaurará las canalizaciones, los conjuntos de datos y los servicios vinculados sin publicar. Si no hay ningún control de código fuente, no es posible recuperar una instancia eliminada del back-end de Azure porque una vez que el servicio recibe el comando de eliminación, la instancia se elimina permanentemente sin ninguna copia de seguridad.

Resolución

Para recuperar una instancia de servicio eliminada que tenga configurado el control de código fuente, consulte los pasos siguientes:

  • Cree una nueva instancia del servicio.

  • Vuelva a configurar Git con los mismos valores, pero asegúrese de importar los recursos existentes al repositorio seleccionado y elija Nueva rama.

  • Cree una solicitud de incorporación de cambios para combinar los cambios con la rama de colaboración y publíquela.

  • Si había un entorno de ejecución de integración autohospedado en una factoría de datos eliminada o un área de trabajo de Synapse, se debe crear una nueva instancia de IR en una nueva factoría o área de trabajo. La instancia de IR local o de máquina virtual debe desinstalarse y reinstalarse, y se obtendrá una nueva clave. Una vez completada la configuración del nuevo entorno de ejecución de integración, el servicio vinculado debe actualizarse para que apunte al nuevo entorno de ejecución de integración y que se pruebe de nuevo la conexión, o se producirá un error de Referencia no válida.

No se puede implementar en una fase diferente mediante el método de publicación automática

Incidencia

El cliente ha seguido todos los pasos necesarios, como instalar el paquete NPM y configurar una fase superior mediante Azure DevOps, pero la implementación sigue produciendo errores.

Causa

Aunque los paquetes de npm se pueden consumir de varias maneras, una de las ventajas principales es su consumo a través de una Canalización de Azure. En cada fusión mediante combinación en la rama de colaboración, se puede desencadenar una canalización que primero valide todo el código y, a continuación, exporte la plantilla de ARM a un artefacto de compilación, que una canalización de versión puede consumir. En la canalización inicial, el archivo YAML debe ser válido y estar completo.

Resolución

La sección siguiente no es válida porque la carpeta package.json no es válida.

- task: Npm@1
  inputs:
    command: 'custom'
    workingDir: '$(Build.Repository.LocalPath)/<folder-of-the-package.json-file>' #replace with the package.json folder
    customCommand: 'run build validate $(Build.Repository.LocalPath) /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/testResourceGroup/providers/Microsoft.DataFactory/factories/yourFactoryName'
  displayName: 'Validate'

Debe incluir DataFactory en customCommand, como "run build validate $(Build.Repository.LocalPath)/DataFactory/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/testResourceGroup/providers/Microsoft.DataFactory/factories/nombreDeSuFábrica". Asegúrese de que el archivo YAML generado para la fase superior tenga los artefactos JSON necesarios.

Izquierda adicional[ mostrado en el archivo JSON publicado

Incidencia

Al publicar con DevOps, se muestra un [ adicional. El servicio agrega una [ más en una plantilla de ARM en DevOps automáticamente. Verá una expresión como [[ en el archivo JSON.

Causa

Dado que [ es un carácter reservado para las plantillas de ARM, se agrega automáticamente un [ adicional para escapar [.

Resolución

Este es el comportamiento normal durante el proceso de publicación para CI/CD.

Realización de CI/CD durante el progreso o la fase en cola de la ejecución de la canalización

Incidencia

Le recomendamos que realice CI/CD durante el progreso o la fase en cola de la ejecución de canalización.

Causa

Cuando la canalización está en curso o en cola, primero debe supervisar la canalización y las actividades. A continuación, puede decidir esperar hasta que finalice la canalización o puede cancelar la ejecución de canalización.

Resolución

Puede supervisar la canalización mediante el SDK, Azure Monitor o Monitor. A continuación, puede seguir los procedimientos recomendados de CI/CD para obtener más instrucciones.

Realización de PRUEBAS UNITARIAS durante el desarrollo e implementación

Incidencia

Le recomendamos que realice pruebas unitarias durante el desarrollo y la implementación de canalizaciones.

Causa

Durante los ciclos de desarrollo e implementación, le recomendamos que realice una prueba unitaria de la canalización antes de publicarla de forma manual o automática. La automatización de pruebas permite ejecutar más pruebas, en menos tiempo, con capacidad de repetición garantizada. Volver a probar automáticamente todas las canalizaciones antes de la implementación le proporciona cierta protección frente a errores de regresión. Las pruebas automatizadas son un componente clave de los enfoques de desarrollo de software de CI/CD: la inclusión de pruebas automatizadas en canalizaciones de implementación de CI/CD puede mejorar significativamente la calidad. A largo plazo, los artefactos de canalización probados se reutilizan, lo que ahorra tiempo y costo.

Resolución

Dado que los clientes pueden tener requisitos de pruebas unitarias diferentes con conjuntos de aptitudes distintos, la práctica habitual es seguir los pasos siguientes:

  1. Configure el proyecto de CI/CD de Azure DevOps o desarrolle una estrategia de pruebas controlada por el SDK de tipo .NET/PYTHON/REST.
  2. En el caso de CI/CD, cree un artefacto de compilación que contenga todos los scripts e implemente recursos en la canalización de versión. Para el enfoque basado en SDK, desarrolle unidades de prueba mediante PyTest en Python, Nunit en C# mediante el SDK de .NET, etc.
  3. Ejecute pruebas unitarias como parte de la canalización de versión o de forma independiente con el SDK de Python/PowerShell/.NET/REST de ADF.

Por ejemplo, imagine que quiere eliminar duplicados en un archivo y, a continuación, almacenar el archivo seleccionado como tabla en una base de datos. Para probar la canalización, configure un proyecto de CI/CD mediante Azure DevOps. Configure una fase de canalización de PRUEBA en la que implemente la canalización desarrollada. Configure la fase de PRUEBA para ejecutar pruebas de Python y asegurarse de que los datos de la tabla son los esperados. Si no usa CI/CD, use Nunit para desencadenar canalizaciones implementadas con las pruebas que desee. Una vez que esté satisfecho con los resultados, puede publicar la canalización en una instancia de producción.

Se produce un error temporal en las ejecuciones de canalización después de la implementación de CI/CD o las actualizaciones de creación

Incidencia

Después de un período de tiempo, las nuevas ejecuciones de canalización comienzan a realizarse correctamente sin ninguna acción del usuario después de errores temporales.

Causa

Hay varios escenarios que pueden desencadenar este comportamiento y todos ellos implican una nueva versión de un recurso dependiente que recibe llamadas de la versión anterior del recurso primario. Por ejemplo, suponga que una canalización secundaria existente llamada por "Execute Pipeline" (Ejecutar canalización) se actualiza para tener los parámetros necesarios y la canalización primaria existente se actualiza para pasar estos parámetros. Si la implementación se produce durante la ejecución de una canalización primaria, pero antes de la actividad Ejecutar canalización, la versión anterior de la canalización llama a la nueva versión de la canalización secundaria y no se pasarán los parámetros esperados. Esto hace que se produzca un error en la canalización con UserError. También puede ocurrir con otros tipos de dependencias, como si se realiza un cambio importante en el servicio vinculado durante una ejecución de canalización que hace referencia a él.

Resolución

Las nuevas ejecuciones de la canalización primaria comenzarán automáticamente a ejecutarse correctamente, por lo que normalmente no se necesita ninguna acción. Sin embargo, para evitar estos errores, los clientes deben tener en cuenta las dependencias al crear y planear implementaciones para evitar cambios importantes.

No se puede parametrizar el tiempo de ejecución de integración en el servicio vinculado

Incidencia

Necesidad de parametrizar el tiempo de ejecución de integración del servicio vinculado

Causa

No se admite esta característica.

Resolución

Debe seleccionar manualmente y establecer un entorno de ejecución de integración. También puede usar la API de PowerShell para cambiarlo. Este cambio puede tener implicaciones posteriores.

Actualización o cambio del entorno de ejecución de integración durante las operaciones de CI/CD

Incidencia

Cambio del nombre del entorno de ejecución de integración durante la implementación de CI/CD.

Causa

No se admite la parametrización de una referencia de entidad (como un entorno de ejecución de integración en un servicio vinculado, un conjunto de datos en una actividad o un servicio vinculado en un conjunto de datos). Al cambiar el nombre del entorno de ejecución durante la implementación, el formato del recurso dependiente (recurso que hace referencia al entorno de ejecución de integración) será incorrecto y tendrá una referencia no válida.

Resolución

En Data Factory es necesario tener el mismo nombre y tipo de entorno de ejecución de integración en todas las fases de CI/CD.

Error en la implementación de plantillas de ARM con el error DataFactoryPropertyUpdateNotSupported

Incidencia

Se produce un error durante la implementación de la plantilla de ARM que es similar a "DataFactoryPropertyUpdateNotSupported: no se admite la actualización del tipo de propiedad".

Causa

La implementación de la plantilla de ARM está intentando cambiar el tipo de un entorno de ejecución de integración existente. Esto no está permitido y provocará un error de implementación porque Data Factory requiere el mismo nombre y tipo de entorno de ejecución de integración en todas las fases de CI/CD.

Resolución

Si quiere compartir entornos de ejecución de integración en todas las fases, considere la posibilidad de usar una factoría ternaria solo para contener los entornos de ejecución de integración compartidos. Puede usar esta factoría compartida en todos los entornos como un tipo de entorno de ejecución de integración vinculado. Para obtener más información, consulte Integración y entrega continuas en Azure Data Factory

Puede producirse un error en la publicación de GIT a causa de archivos PartialTempTemplates

Incidencia

Si tiene miles de archivos JSON temporales de plantillas de ARM antiguas en la carpeta PartialTemplates, puede producirse un error en la publicación.

Causa

Al publicar, ADF captura todos los archivos de dentro de cada carpeta de la rama de colaboración. En el pasado, la publicación generaba dos carpetas en la rama de publicación: PartialArmTemplates y LinkedTemplates. Ya no se generan archivos PartialArmTemplates. Pero, dado que puede haber muchos archivos antiguos (miles) en la carpeta PartialArmTemplates, esto puede dar lugar a que se realicen muchas solicitudes a GitHub al publicar y se alcance el límite.

Resolución

Elimine la carpeta PartialTemplates y vuelva a publicarla. También puede eliminar los archivos temporales de esa carpeta.

La opción Incluir parámetros globales en la plantilla de ARM no funciona

Incidencia

Si usa una plantilla de parametrización predeterminada antigua, el nuevo método para incluir parámetros globales del Centro de administración no funcionará.

Causa

La plantilla de parametrización predeterminada debe incluir todos los valores de la lista global de parámetros.

Resolución

  • Use la plantilla de parametrización predeterminada actualizada como sistema de migración única al nuevo método de inclusión de parámetros globales. Esta plantilla hace referencia a todos los valores de la lista de parámetros globales. También tiene que actualizar la tarea de implementación en la canalización de versión si ya ha empezado a reemplazar los parámetros de plantilla allí.
  • Actualice los nombres de parámetros de plantilla en la canalización de CI/CD si ya está reemplazando los parámetros de plantilla (por parámetros globales).

Código de error: InvalidTemplate

Incidencia

Se muestra un mensaje que indica No se puede analizar la expresión. Una expresión que se pasa dentro del contenido dinámico de una actividad no se está procesando correctamente debido a un error de sintaxis.

Causa

El contenido dinámico no está escrito según los requisitos del lenguaje de expresión.

Resolución

  • Para realizar una ejecución de depuración, compruebe las expresiones en la canalización que se ubica en la rama git más reciente.
  • Para realizar una ejecución desencadenada, compruebe las expresiones en la canalización ubicada en el modo Real .

Contenido relacionado

Para obtener más ayuda para solucionar problemas, pruebe los siguientes recursos: