Transformación de datos mediante la actividad de script en Azure Data Factory o Synapse Analytics

Artículo
10/20/2023

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 información sobre cómo iniciar una nueva evaluación gratuita.

Las actividades de transformación de una canalización de Data Factory o Synapse se usan para transformar y procesar los datos sin procesar a fin de convertirlos en predicciones y conclusiones. La actividad de script es una de las actividades de transformación que admiten las canalizaciones. Este artículo se basa en el artículo sobre transformación de datos, que presenta información general de la transformación de datos y las actividades de transformación admitidas.

Mediante la actividad de script, puede ejecutar operaciones comunes con lenguaje de manipulación de datos (DML) y lenguaje de definición de datos (DDL). Las instrucciones DML como INSERT, UPDATE, DELETE y SELECT permiten a los usuarios insertar, modificar, eliminar y recuperar datos en la base de datos. Las instrucciones DDL como CREATE, ALTER y DROP permiten a un administrador de base de datos crear, modificar y eliminar objetos de base de datos como tablas, índices y usuarios.

Puede usar la actividad de script para invocar un script de SQL en uno de los siguientes almacenes de datos de la empresa o en una máquina virtual de Azure:

Azure SQL Database
Azure Synapse Analytics
Base de datos de SQL Server. Si se usa SQL Server, se debe instalar el entorno de ejecución de integración autohospedado en el mismo equipo que hospeda la base de datos o en un equipo independiente que tenga acceso a la base de datos. El entorno de ejecución de integración autohospedado es un componente que conecta orígenes de datos locales o en la máquina virtual de Azure con servicios en la nube de forma segura y administrada. Consulte el artículo Entorno de ejecución de integración autohospedado para más información.
Oracle
Snowflake

El script puede contener una sola instrucción SQL o múltiples instrucciones SQL que se ejecutarán de forma secuencial. Puede usar la tarea Script para los siguientes fines:

Truncar una tabla en preparación para insertar datos.
Crear, modificar y quitar objetos de base de datos, como tablas y vistas.
Volver a crear tablas de hechos y tablas de dimensiones antes de cargar datos en ellas.
Ejecutar procedimientos almacenados. Si la instrucción SQL invoca un procedimiento almacenado que devuelve resultados de una tabla temporal, use la opción WITH RESULT SETS para definir los metadatos del conjunto de resultados.
Guarde el conjunto de filas devuelto de una consulta como salida de actividad para el consumo en niveles inferiores.

Detalles de la sintaxis

Este es el formato JSON para definir una actividad de script:

{ 
   "name": "<activity name>", 
   "type": "Script", 
   "linkedServiceName": { 
      "referenceName": "<name>", 
      "type": "LinkedServiceReference" 
    }, 
   "typeProperties": { 
      "scripts" : [ 
         { 
            "text": "<Script Block>", 
            "type": "<Query> or <NonQuery>", 
            "parameters":[ 
               { 
                  "name": "<name>", 
                  "value": "<value>", 
                  "type": "<type>", 
                  "direction": "<Input> or <Output> or <InputOutput>", 
                  "size": 256 
               }, 
               ... 
            ] 
         }, 
         ... 
      ],     
         ... 
         ] 
      }, 
      "scriptBlockExecutionTimeout": "<time>",  
      "logSettings": { 
         "logDestination": "<ActivityOutput> or <ExternalStore>", 
         "logLocationSettings":{ 
            "linkedServiceName":{ 
               "referenceName": "<name>", 
               "type": "<LinkedServiceReference>" 
            }, 
            "path": "<folder path>" 
         } 
      } 
    } 
}

En la tabla siguiente se describen estas propiedades JSON:

Nombre de la propiedad	Descripción	Obligatorio
name	El nombre de la actividad.	Sí
type	El tipo de la actividad, establecido en "Script".	Sí
typeProperties	Especifique las propiedades para configurar la actividad de script.	Sí
linkedServiceName	La base de datos de destino en la que se ejecuta el script. Debe ser una referencia a un servicio vinculado.	Sí
scripts	Una matriz de objetos para representar el script.	No
scripts.text	El texto sin formato de un bloque de consultas.	No
scripts.type	El tipo del bloque de consultas. Puede ser Query o NonQuery. Valor predeterminado: Query.	No
scripts.parameter	La matriz de parámetros del script.	No
scripts.parameter.name	El nombre del parámetro.	No
scripts.parameter.value	Valor del parámetro.	No
scripts.parameter.type	El tipo de datos del parámetro. El tipo es de tipo lógico y sigue la asignación de tipos de cada conector.	No
scripts.parameter.direction	La dirección del parámetro. Puede ser Input, Output, InputOutput. El valor se omite si la dirección es Output. No se admite el tipo ReturnValue. Establezca el valor devuelto de SP en un parámetro de salida para recuperarlo.	No
scripts.parameter.size	El tamaño máximo del parámetro. Solo se aplica al parámetro de dirección Output/InputOutput del tipo cadena o byte[].	No
scriptBlockExecutionTimeout	El tiempo de espera para que se complete la operación de ejecución del bloque de script antes de que se agote el tiempo de espera.	No
logSettings	La configuración para almacenar los registros de salida. Si no se especifica, el registro de script está deshabilitado.	No
logSettings.logDestination	El destino de la salida del registro. Puede ser ActivityOutput o ExternalStore. Valor predeterminado: ActivityOutput.	No
logSettings.logLocationSettings	La configuración de la ubicación de destino si logDestination es ExternalStore.	No
logSettiongs.logLocationSettings.linkedServiceName	El servicio vinculado de la ubicación de destino. Solo se admite Blob Storage.	No
logSettings.logLocationSettings.path	La ruta de acceso de la carpeta en la que se almacenarán los registros.	No

Salida de la actividad

Salida del ejemplo:

{ 
    "resultSetCount": 2, 
    "resultSets": [ 
        { 
            "rowCount": 10, 
            "rows":[ 
                { 
                    "<columnName1>": "<value1>", 
                    "<columnName2>": "<value2>", 
                    ... 
                } 
            ] 
        }, 
        ... 
    ], 
    "recordsAffected": 123, 
    "outputParameters":{ 
        "<parameterName1>": "<value1>", 
        "<parameterName2>": "<value2>" 
    }, 
    "outputLogs": "<logs>", 
    "outputLogsLocation": "<folder path>", 
    "outputTruncated": true, 
    ... 
}

Nombre de la propiedad	Descripción	Condición
resultSetCount	El recuento de conjuntos de resultados que el script devuelve.	Siempre
resultSets	La matriz que contiene todos los conjuntos de resultados.	Siempre
resultSets.rowCount	El número total de filas del conjunto de resultados.	Siempre
resultSets.rows	La matriz de filas del conjunto de resultados.	Siempre
recordsAffected	El número de las filas afectadas por el script.	Si scriptType es NonQuery.
outputParameters	Los parámetros de salida del script.	Si el tipo de parámetro es Output o InputOutput.
outputLogs	Los registros que escribe el script, por ejemplo, la instrucción print.	Si el conector admite la instrucción de registro y enableScriptLogs es true y no se proporciona logLocationSettings.
outputLogsPath	La ruta de acceso completa del archivo de registro.	Si enableScriptLogs es true y se proporciona logLocationSettings.
outputTruncated	Indicador de si la salida supera los límites y se trunca.	Si la salida supera los límites.

Nota:

La salida se recopila cada vez que se ejecuta un bloque de scripts. La salida final es el resultado combinado de todas las salidas de bloque de scripts. Se sobrescribirán los parámetros de salida con el mismo nombre en un bloque de scripts diferente.
Dado que la salida tiene una limitación de tamaño o filas, la salida se truncará en el siguiente orden: registros -> parámetros -> filas. Tenga en cuenta que esto se aplica a un único bloque de scripts, lo que significa que las filas de salida del siguiente bloque de scripts no expulsarán los registros anteriores.
Cualquier error causado por el registro no producirá un error en la actividad.
Para más información sobre la salida de la actividad de consumo resultSets en una actividad de nivel inferior, consulte la documentación sobre el resultado de la actividad de búsqueda.
Use outputLogs cuando use instrucciones "PRINT" con fines de registro. Si la consulta devuelve resultSets, estará disponible en la salida de la actividad y estará limitada a 5 000 filas/límite de tamaño de 4 MB.

Configuración de la actividad de script mediante la interfaz de usuario

Script en línea

Screenshot showing the UI to configure an inline script.

Los scripts en línea se integran bien con la CI/CD de canalización, ya que el script se almacena como parte de los metadatos de la canalización.

Registro

Screenshot showing the UI for the logging settings for a script.

Opciones de registro:

Deshabilitar : no se registra ninguna salida de ejecución.
Salida de actividad : la salida de ejecución del script se asocia a la salida de la actividad. Las actividades de los niveles inferiores podrán utilizarla. El tamaño de salida está limitado a 4 MB.
Almacenamiento externo : conserva la salida en el almacenamiento. Use esta opción si el tamaño de salida es superior a 2 MB o desea conservar explícitamente la salida en la cuenta de almacenamiento.

Nota:

Facturación : la actividad de script se facturará como actividades de canalización.

Vea los siguientes artículos, en los que se explica cómo transformar datos de otras maneras: