Procedimientos para usar parámetros, expresiones y funciones en Azure Data Factory
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 documento, nos centraremos principalmente en aprender conceptos fundamentales con varios ejemplos para explorar la capacidad de crear canalizaciones de datos parametrizados en Azure Data Factory. La parametrización y las expresiones dinámicas son importantes adiciones a ADF porque pueden ahorrar mucho tiempo y permiten una solución de extracción, transformación y carga de datos (ETL) o de extracción, carga de datos y transformación (ELT) mucho más flexible, lo que reduce drásticamente el coste del mantenimiento de la solución y acelera la implementación de nuevas características en las canalizaciones existentes. Estas mejoras se deben a que la parametrización reduce la cantidad de codificación de forma rígida y aumenta el número de objetos y procesos reutilizables en una solución.
Interfaz de usuario y parámetros de Azure Data Factory
Si no está familiarizado con el uso de parámetros de Azure Data Factory en la interfaz de usuario de ADF, revise Interfaz de usuario de Data Factory para los servicios vinculados con parámetros e Interfaz de usuario de Data Factory para la canalización controlada por metadatos con parámetros para obtener una explicación visual.
Conceptos de parámetros y expresiones
Puede usar parámetros para pasar valores externos a canalizaciones, conjuntos de datos, servicios vinculados y flujos de datos. Una vez que el parámetro se ha pasado al recurso, no se puede cambiar. Mediante la parametrización de recursos, puede reutilizarlos con valores diferentes cada vez. Los parámetros se pueden utilizar individualmente o como parte de expresiones. Los valores JSON de la definición pueden ser literales o expresiones que se evalúan en tiempo de ejecución.
Por ejemplo:
"name": "value"
or
"name": "@pipeline().parameters.password"
Las expresiones pueden aparecer en cualquier lugar de un valor de cadena JSON y devolver siempre otro valor JSON. Aquí, password es un parámetro de canalización de la expresión. Si un valor JSON es una expresión, se extrae el cuerpo de la expresión quitando el signo arroba (@). Si se necesita una cadena literal que empiece por @, debe convertirse con @@. Los ejemplos siguientes muestran cómo se evalúan las expresiones.
| Valor JSON | Resultado |
|---|---|
| "parameters" | Se devuelven los caracteres de "parameters". |
| "parameters[1]" | Se devuelven los caracteres de "parameters[1]". |
| "@@" | Se devuelve una cadena de 1 carácter que contiene \"\@\". |
| " @" | Se devuelve una cadena de 2 caracteres que contienen \" \@\". |
Las expresiones también pueden aparecer dentro de las cadenas mediante una característica llamada interpolación de cadenas, donde las expresiones se ajustan en @{ ... }. Por ejemplo: "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"
Con la interpolación de cadena, el resultado siempre es una cadena. Supongamos que se ha definido myNumber como 42 y myString como foo:
| Valor JSON | Resultado |
|---|---|
| "@pipeline().parameters.myString" | Devuelve foo como una cadena. |
| "@{pipeline().parameters.myString}" | Devuelve foo como una cadena. |
| "@pipeline().parameters.myNumber" | Devuelve 42 como un número. |
| "@{pipeline().parameters.myNumber}" | Devuelve 42 como una cadena. |
| "Answer is: @{pipeline().parameters.myNumber}" | Devuelve la cadena Answer is: 42. |
| "@concat('Answer is: ', string(pipeline().parameters.myNumber))" | Devuelve la cadena Answer is: 42. |
| "Answer is: @@{pipeline().parameters.myNumber}" | Devuelve la cadena Answer is: @{pipeline().parameters.myNumber}. |
Ejemplos de uso de parámetros en expresiones
Ejemplo de expresión compleja
En el ejemplo siguiente se muestra un ejemplo complejo que hace referencia a un subcampo profundo de la salida de la actividad. Para hacer referencia a un parámetro de canalización que se evalúa como un subcampo, use la sintaxis [] en lugar del operador punto (.) (como en el caso de subfield1 y subfield2)
@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*
Editor de contenido dinámico
El editor de contenido dinámico convierte automáticamente los caracteres de escape en el contenido cuando finaliza la edición. Por ejemplo, el contenido siguiente del editor de contenido es una interpolación de cadenas con dos funciones de expresión.
{
"type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
"name": "@{toUpper('myData')}"
}
El editor de contenido dinámico convierte el contenido anterior en la expresión "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}". El resultado de esta expresión es la cadena de formato JSON que se muestra a continuación.
{
"type": "Table",
"name": "MYDATA"
}
Conjunto de datos con parámetros
En el ejemplo siguiente, BlobDataset toma un parámetro llamado path. Su valor se usa para establecer un valor para la propiedad folderPath mediante la expresión: dataset().path.
{
"name": "BlobDataset",
"properties": {
"type": "AzureBlob",
"typeProperties": {
"folderPath": "@dataset().path"
},
"linkedServiceName": {
"referenceName": "AzureStorageLinkedService",
"type": "LinkedServiceReference"
},
"parameters": {
"path": {
"type": "String"
}
}
}
}
Canalización con parámetros
En el ejemplo siguiente, la canalización toma los parámetros inputPath y outputPath. El valor de path para el conjunto de datos del blob con parámetros se establece mediante el uso de los valores de estos parámetros. La sintaxis utilizada aquí es: pipeline().parameters.parametername.
{
"name": "Adfv2QuickStartPipeline",
"properties": {
"activities": [
{
"name": "CopyFromBlobToBlob",
"type": "Copy",
"inputs": [
{
"referenceName": "BlobDataset",
"parameters": {
"path": "@pipeline().parameters.inputPath"
},
"type": "DatasetReference"
}
],
"outputs": [
{
"referenceName": "BlobDataset",
"parameters": {
"path": "@pipeline().parameters.outputPath"
},
"type": "DatasetReference"
}
],
"typeProperties": {
"source": {
"type": "BlobSource"
},
"sink": {
"type": "BlobSink"
}
}
}
],
"parameters": {
"inputPath": {
"type": "String"
},
"outputPath": {
"type": "String"
}
}
}
}
Llamada a funciones dentro de expresiones
Puede llamar a funciones dentro de expresiones. En las siguientes secciones se proporciona información sobre las funciones que se pueden usar en una expresión.
Funciones de cadena
Para trabajar con cadenas, puede usar estas funciones de cadena y también algunas funciones de colección. Las funciones de cadena solo funcionan en cadenas.
| Función de cadena | Tarea |
|---|---|
| concat | Combina dos o más cadenas y devuelve la cadena combinada. |
| endsWith | Comprueba si una cadena termina con la subcadena especificada. |
| guid | Genera un identificador único global (GUID) como una cadena. |
| indexOf | Devuelve la posición inicial de una subcadena. |
| lastIndexOf | Devuelve la posición inicial de la última repetición de una subcadena. |
| replace | Reemplaza una subcadena por la cadena especificada y devuelve la cadena actualizada. |
| split | Devuelve una matriz que contiene subcadenas, separadas por comas, de una cadena mayor en función de un carácter delimitador especificado en la cadena original. |
| startsWith | Comprueba si una cadena comienza con una subcadena especificada. |
| substring | Devuelve caracteres de una cadena, a partir de la posición especificada. |
| toLower | Devuelve una cadena en formato de minúsculas. |
| toUpper | Devuelve una cadena en formato de mayúsculas. |
| trim | Quita el espacio en blanco inicial y final de una cadena y devuelve la cadena actualizada. |
Funciones de colección
Para trabajar con colecciones, por lo general matrices, cadenas y, en ocasiones, diccionarios, puede usar estas funciones de colección.
| Función de colección | Tarea |
|---|---|
| contains | Comprueba si una colección contiene un elemento específico. |
| empty | Comprueba si una colección está vacía. |
| first | Devuelve el primer elemento de una colección. |
| intersection | Devuelve una colección que tiene solo los elementos comunes en las colecciones especificadas. |
| join | Devuelve una cadena que tiene todos los elementos de una matriz, separados por el carácter especificado. |
| last | Devuelve el último elemento de una colección. |
| length | Devuelve el número de elementos de una cadena o una matriz. |
| skip | Quita elementos del principio de una colección y devuelve todos los demás elementos. |
| take | Devuelve elementos del principio de una colección. |
| union | Devuelve una colección que tiene todos los elementos de las colecciones especificadas. |
Funciones lógicas
Estas funciones son útiles en las condiciones y se pueden usar para evaluar cualquier tipo de lógica.
| Función de comparación lógica | Tarea |
|---|---|
| and | Comprueba si todas las expresiones son true. |
| equals | Comprueba si ambos valores son equivalentes. |
| greater | Comprueba si el primer valor es mayor que el segundo. |
| greaterOrEquals | Comprueba si el primer valor es mayor o igual que el segundo. |
| if | Comprueba si una expresión es true o false. En función del resultado, devuelve un valor especificado. |
| less | Comprueba si el primer valor es menor que el segundo. |
| lessOrEquals | Compruebe si el primer valor es menor o igual que el segundo valor. |
| not | Comprueba si una expresión es false. |
| or | Comprueba si al menos una expresión es true. |
Funciones de conversión
Estas funciones se utilizan para convertir en cada uno de los tipos nativos del idioma:
- string
- integer
- FLOAT
- boolean
- arrays
- dictionaries
| Función de conversión | Tarea |
|---|---|
| array | Devuelve una matriz a partir de una única entrada especificada. Para varias entradas, consulte createArray. |
| base64 | Devuelve la versión de una cadena codificada en base64. |
| base64ToBinary | Devuelve la versión binaria de una cadena codificada en base64. |
| base64ToString | Devuelve la versión de cadena de una cadena codificada en base64. |
| binary | Devuelve la versión binaria de un valor de entrada. |
| bool | Devuelve la versión booleana de un valor de entrada. |
| coalesce | Devuelve el primer valor distinto de null de uno o más parámetros. |
| createArray | Devuelve una matriz a partir de varias entradas. |
| dataUri | Devuelve el URI de datos de un valor de entrada. |
| dataUriToBinary | Devuelve la versión binaria de un URI de datos. |
| dataUriToString | Devuelve la versión de cadena de un URI de datos. |
| decodeBase64 | Devuelve la versión de cadena de una cadena codificada en base64. |
| decodeDataUri | Devuelve la versión binaria de un URI de datos. |
| decodeUriComponent | Devuelve una cadena que reemplaza los caracteres de escape por versiones descodificadas. |
| encodeUriComponent | Devuelve una cadena que reemplaza los caracteres no seguros de la dirección URL por caracteres de escape. |
| float | Devuelve un número de punto flotante de un valor de entrada. |
| int | Devuelve la versión como número entero de una cadena. |
| json | Devuelve el valor o el objeto de tipo Notación de objetos JavaScript (JSON) de una cadena o XML. |
| string | Devuelve la versión de cadena de un valor de entrada. |
| uriComponent | Devuelve la versión codificada con el URI de un valor de entrada mediante la sustitución de los caracteres no seguros de la dirección URL por caracteres de escape. |
| uriComponentToBinary | Devuelve la versión binaria de una cadena codificada con el URI. |
| uriComponentToString | Devuelve la versión de cadena de una cadena codificada con el URI. |
| xml | Devuelve la versión XML de una cadena. |
| xpath | Comprueba el código XML de los nodos o valores que coinciden con una expresión XPath (XML Path Language) y devuelve los nodos o valores coincidentes. |
Funciones matemáticas
Estas funciones pueden utilizarse para ambos tipos de números: enteros y flotantes.
| Función matemática | Tarea |
|---|---|
| add | Devuelve el resultado de sumar dos números. |
| div | Devuelve el resultado de dividir dos números. |
| max | Devuelve el valor más alto de un conjunto de números o una matriz. |
| min | Devuelve el valor más bajo de un conjunto de números o una matriz. |
| mod | Devuelve el resto de dividir dos números. |
| mul | Devuelve el producto de multiplicar dos números. |
| rand | Devuelve un entero aleatorio desde un intervalo especificado. |
| range | Devuelve una matriz de enteros que comienza en un entero especificado. |
| sub | Devuelve el resultado de restar el segundo número del primero. |
Funciones de fecha
| Función de fecha u hora | Tarea |
|---|---|
| addDays | Agrega un número de días a una marca de tiempo. |
| addHours | Agrega un número de horas a una marca de tiempo. |
| addMinutes | Agrega un número de minutos a una marca de tiempo. |
| addSeconds | Agrega un número de segundos a una marca de tiempo. |
| addToTime | Agrega un número de unidades de tiempo a una marca de tiempo. Consulte también getFutureTime. |
| convertFromUtc | Convierte una marca de tiempo del formato Hora Universal Coordinada (UTC) a la zona horaria de destino. |
| convertTimeZone | Convierte una marca de tiempo de la zona horaria de origen a la zona horaria de destino. |
| convertToUtc | Convierte una marca de tiempo de la zona horaria de origen al formato Hora Universal Coordinada (UTC). |
| dayOfMonth | Devuelve el día del componente de mes de una marca de tiempo. |
| dayOfWeek | Devuelve el día del componente de semana de una marca de tiempo. |
| dayOfYear | Devuelve el día del componente de año de una marca de tiempo. |
| formatDateTime | Devuelve la marca de tiempo como cadena en formato opcional. |
| getFutureTime | Devuelve la marca de tiempo actual más las unidades de tiempo especificadas. Consulte también addToTime. |
| getPastTime | Devuelve la marca de tiempo actual menos las unidades de tiempo especificadas. Consulte también subtractFromTime. |
| startOfDay | Devuelve el inicio del día de una marca de tiempo. |
| startOfHour | Devuelve el inicio de la hora de una marca de tiempo. |
| startOfMonth | Devuelve el inicio del mes de una marca de tiempo. |
| subtractFromTime | Resta un número de unidades de tiempo de una marca de tiempo. Consulte también getPastTime. |
| ticks | Devuelve el valor de la propiedad ticks de una marca de tiempo especificada. |
| utcNow | Devuelve la marca de tiempo actual como una cadena. |
Ejemplos detallados para practicar
Canalización detallada de copia de Azure Data Factory con parámetros
Este tutorial para pasar parámetros de canalización de copia de Azure Data Factory le guiará en el proceso de pasar parámetros entre una canalización y una actividad, así como entre actividades.
Canalización detallada de flujo de datos de asignación con parámetros
Siga el flujo de datos de asignación con parámetros para obtener un ejemplo completo sobre cómo usar los parámetros en el flujo de datos.
Canalización detallada controlada por metadatos con parámetros
Siga la canalización controlada por metadatos con parámetros para obtener más información sobre cómo usar los parámetros para diseñar canalizaciones controladas por metadatos. Este es un caso de uso popular para los parámetros.
Contenido relacionado
Para obtener una lista de las variables del sistema que se pueden usar en las expresiones, vea Variables del sistema.