Transformación de datos mediante la ejecución de un cuaderno de Synapse

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.

La actividad de cuaderno de Azure Synapse de una canalización de Synapse ejecuta un cuaderno de Synapse en el área de trabajo de Azure Synapse. Este artículo se basa en el artículo sobre actividades de transformación de datos , que presenta información general de la transformación de datos y las actividades de transformación admitidas. 

Creación de una actividad de cuaderno de Synapse

Puede crear una actividad de cuaderno de Synapse directamente desde el lienzo de la canalización de Synapse o desde el editor de cuadernos. La actividad de cuaderno de Synapse se ejecuta en el grupo de Spark que se elige en el cuaderno de Synapse.

Adición de una actividad de cuaderno de Synapse desde el lienzo de la canalización

Arrastre y coloque el cuaderno de Synapse hasta Activities (Actividades) en el lienzo de la canalización de Synapse. Seleccione el cuadro de actividad del cuaderno de Synapse y configure el contenido del cuaderno para la actividad actual en la configuración. Puede seleccionar un cuaderno existente del área de trabajo actual o agregar uno nuevo.

Si selecciona un cuaderno existente del área de trabajo actual, puede hacer clic en el botón Abrir para abrir directamente la página del cuaderno.

Como alternativa, puede reconfigurar las opciones Spark pool\Executor size\Dynamically allocate executors\Min executors\Max executors\Driver size. Debe tenerse en cuenta que las opciones que se reconfiguren aquí reemplazarán las opciones de la sesión de configuración en Notebook. Si no establece nada en la configuración de la actividad del cuaderno actual, se ejecutará con la configuración de la sesión de configuración en ese cuaderno.

Propiedad	Descripción	Obligatorio
Grupo de Spark	Referencie el grupo de Spark. Puede seleccionar el grupo de Apache Spark en la lista. Si esta configuración está vacía, se ejecutará en el grupo de Spark del propio cuaderno.	No
Executor size (Tamaño del ejecutor)	El número de núcleos y la memoria que se usarán para los ejecutores asignados en el grupo de Spark especificado para la sesión.	No
Asignación dinámica de ejecutores	Esta configuración se asigna a la propiedad de asignación dinámica de la configuración de Spark para la asignación de ejecutores de aplicaciones de Spark.	No
Mínimo de ejecutores	Número mínimo de ejecutores que se asignarán en el grupo de Spark especificado para el trabajo.	No
Máximo de ejecutores	Número máximo de ejecutores que se asignarán en el grupo de Spark especificado para el trabajo.	No
Driver size (Tamaño del controlador)	Número de núcleos y memoria que se van a usar para el controlador proporcionado en el grupo de Apache Spark especificado para el trabajo.	No

Nota

La ejecución de cuadernos de Spark en paralelo en canalizaciones de Azure Synapse se pone en cola y se ejecuta de forma FIFO, el orden de los trabajos en la cola lo determina la secuencia de tiempo, el tiempo de expiración de un trabajo en la cola es de 3 días. Tenga en cuenta que la cola de cuadernos solo funciona en la canalización de Synapse.

Adición de un cuaderno a la canalización de Synapse

Seleccione el botón Agregar a la canalización en la esquina superior derecha para agregar un cuaderno a una canalización existente o crear una canalización.

Pasar parámetros

Designación de una celda de parámetros

Para parametrizar el cuaderno, seleccione los puntos suspensivos (...) para obtener acceso a más comandos en la barra de herramientas de la celda. A continuación, seleccione Toggle parameter cell (Alternar celda de parámetros) para designar la celda como la celda de parámetros.

Azure Data Factory busca la celda de parámetros y utiliza los valores como valores predeterminados para los parámetros que se pasan en tiempo de ejecución. El motor de ejecución agregará una nueva celda debajo de la celda de parámetros con los parámetros de entrada que van a sobrescribir los valores predeterminados.

Asignación de valores de parámetros de una canalización

Una vez que haya creado un cuaderno con parámetros, podrá ejecutarlo desde una canalización con la actividad de cuaderno de Synapse. Después de agregar la actividad al lienzo de la canalización, podrá establecer los valores de los parámetros en la sección Base parameters (Parámetros base) de la pestaña Settings (Configuración).

Al asignar valores de parámetros, puede usar el lenguaje de expresiones de canalización o las variables del sistema.

Lectura del valor de salida de la celda del cuaderno de Synapse

Puede leer el valor de salida de la celda del cuaderno en las actividades siguientes siguiendo estos pasos:

1. Llame a la API mssparkutils.notebook.exit en la actividad de cuaderno de Synapse para devolver el valor que desea mostrar en la salida de la actividad, por ejemplo:

   mssparkutils.notebook.exit("hello world") 
   

   Al guardar el contenido del cuaderno y volver a desencadenar la canalización, la salida de la actividad de cuaderno contendrá la propiedad exitValue, que se puede consumir en las actividades siguientes en el paso 2.

2. Lea la propiedad exitValue de la salida de la actividad de cuaderno. Esta es una expresión de ejemplo que se usa para comprobar si el valor de exitValue capturado de la salida de la actividad de cuaderno es igual a "hello world":

   

Ejecución de otro cuaderno de Synapse

Puede hacer referencia a otros cuadernos de una actividad de cuaderno de Synapse mediante una llamada a %run magic o las utilidades de cuaderno mssparkutils. Ambos admiten llamadas de función de anidamiento. Las diferencias principales entre estos dos métodos que debe tener en cuenta en función de su escenario son:

• %run magic copia todas las celdas del cuaderno al que se hace referencia en la celda %run y comparte el contexto de variables. Cuando notebook1 hace referencia a notebook2 mediante %run notebook2 y notebook2 llama a una función mssparkutils.notebook.exit, se detendrá la ejecución de celdas en notebook1. Se recomienda usar %run magic cuando quiera "incluir" un archivo de cuaderno.
• mssparkutils notebook utilities llama al cuaderno al que se hace referencia como un método o una función. No se comparte el contexto de variables. Cuando notebook1 hace referencia a notebook2 mediante mssparkutils.notebook.run("notebook2") y notebook2 llama a una función mssparkutils.notebook.exit, la ejecución de celdas en notebook1 continuará. Se recomienda usar las utilidades de cuaderno mssparkutils cuando quiera "importar" un cuaderno.

Visualización del historial de ejecución de la actividad de cuaderno

Vaya a Pipeline runs (Ejecuciones de canalización) en la pestaña Monitor (Supervisión); verá la canalización que ha desencadenado. Abra la canalización que contiene la actividad de cuaderno para ver el historial de ejecución.

Para ver la instantánea de ejecución del cuaderno más reciente, incluida la entrada y la salida de las celdas, seleccione el botón Open notebook (Abrir cuaderno).

Abrir instantánea del bloc de notas:

Para ver la entrada o la salida de la actividad de cuaderno, seleccione el botón de entrada o salida. Si se produce un error de usuario en la canalización, seleccione la salida para comprobar el campo result (resultado) y ver el seguimiento de errores de usuario detallado.

Definición de la actividad de cuaderno de Synapse

Este es un ejemplo de definición JSON de una actividad de cuaderno de Synapse:

{
    "name": "parameter_test",
    "type": "SynapseNotebook",
    "dependsOn": [],
    "policy": {
        "timeout": "7.00:00:00",
        "retry": 0,
        "retryIntervalInSeconds": 30,
        "secureOutput": false,
        "secureInput": false
    },
    "userProperties": [],
    "typeProperties": {
        "notebook": {
            "referenceName": "parameter_test",
            "type": "NotebookReference"
        },
        "parameters": {
            "input": {
                "value": {
                    "value": "@pipeline().parameters.input",
                    "type": "Expression"
                }
            }
        }
    }
}

Salida de la actividad de cuaderno de Synapse

Este es un ejemplo en formato JSON de la salida de una actividad de cuaderno de Synapse:

{
{
    "status": {
        "Status": 1,
        "Output": {
            "status": <livySessionInfo>
            },
            "result": {
                "runId": "<GUID>",
                "runStatus": "Succeed",
                "message": "Notebook execution is in Succeeded state",
                "lastCheckedOn": "2021-03-23T00:40:10.6033333Z",
                "errors": {
                    "ename": "",
                    "evalue": ""
                },
                "sessionId": 4,
                "sparkpool": "sparkpool",
                "snapshotUrl": "https://myworkspace.dev.azuresynapse.net/notebooksnapshot/{guid}",
                "exitCode": "abc" // return value from user notebook via mssparkutils.notebook.exit("abc")
            }
        },
        "Error": null,
        "ExecutionDetails": {}
    },

    "effectiveIntegrationRuntime": "DefaultIntegrationRuntime (West US 2)",
    "executionDuration": 234,
    "durationInQueue": {
        "integrationRuntimeQueue": 0
    },
    "billingReference": {
        "activityType": "ExternalActivity",
        "billableDuration": [
            {
                "meterType": "AzureIR",
                "duration": 0.06666666666666667,
                "unit": "Hours"
            }
        ]
    }
}

Problemas conocidos

Si el nombre del cuaderno está parametrizado en la actividad Cuaderno de canalización, no se puede hacer referencia a la versión del cuaderno con el estado no publicado en las ejecuciones de depuración.