Transformar os dados com um bloco de notas do Synapse

Artigo
07/27/2023

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange tudo, desde o movimento de dados à ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma nova versão de avaliação gratuitamente!

A atividade Azure Synapse bloco de notas num pipeline do Synapse executa um bloco de notas do Synapse na sua área de trabalho Azure Synapse. Este artigo baseia-se no artigo atividades de transformação de dados , que apresenta uma descrição geral da transformação de dados e das atividades de transformação suportadas.

Criar uma atividade de bloco de notas do Synapse

Pode criar uma atividade de bloco de notas do Synapse diretamente a partir da tela do pipeline do Synapse ou do editor de blocos de notas. A atividade do bloco de notas do Synapse é executada no conjunto do Spark que é escolhido no bloco de notas do Synapse.

Adicionar uma atividade de bloco de notas do Synapse a partir da tela de pipeline

Arraste e largue o bloco de notas do Synapse em Atividades para a tela do pipeline do Synapse. Selecione na caixa de atividade do bloco de notas do Synapse e confira o conteúdo do bloco de notas para a atividade atual nas definições. Pode selecionar um bloco de notas existente na área de trabalho atual ou adicionar um novo.

Se selecionar um bloco de notas existente na área de trabalho atual, pode clicar no botão Abrir para abrir diretamente a página do bloco de notas.

(Opcional) Também pode reconfigurar o conjunto do Spark\Tamanho do executor\Alocar dinamicamente executores\Executores Min\Max executors\Tamanho do controlador nas definições. Deve ser notado que as definições reconfiguradas aqui irão substituir as definições da sessão de configuração no Bloco de Notas. Se nada estiver definido nas definições da atividade atual do bloco de notas, será executado com as definições da sessão de configuração nesse bloco de notas.

screenshot-showing-create-notebook-activity

Propriedade	Descrição	Obrigatório
Conjunto do Spark	Referência ao conjunto do Spark. Pode selecionar o conjunto do Apache Spark na lista. Se esta definição estiver vazia, será executada no conjunto spark do próprio bloco de notas.	No
Tamanho do executor	Número de núcleos e memória a utilizar para executores alocados no conjunto do Apache Spark especificado para a sessão.	No
Alocar dinamicamente executores	Esta definição mapeia para a propriedade de alocação dinâmica na configuração do Spark para alocação de executores da Aplicação Spark.	No
Executores min	Número mínimo de executores a atribuir no conjunto do Spark especificado para a tarefa.	No
Máx. executors	Número máximo de executores a atribuir no conjunto do Spark especificado para a tarefa.	No
Tamanho do controlador	Número de núcleos e memória a utilizar para o controlador indicado no conjunto do Apache Spark especificado para a tarefa.	No

Nota

A execução de Blocos de Notas do Spark paralelos no Azure Synapse os pipelines são em fila de espera e executados de forma FIFO, a ordem das tarefas na fila é de acordo com a sequência de tempo, a hora de expiração de uma tarefa na fila é de 3 dias. Repare que a fila para o bloco de notas só funciona no pipeline do synapse.

Adicionar um bloco de notas ao pipeline do Synapse

Selecione o botão Adicionar ao pipeline no canto superior direito para adicionar um bloco de notas a um pipeline existente ou criar um novo pipeline.

screenshot-showing-add-notebook-to-pipeline

Transmitir parâmetros

Designar uma célula de parâmetros

Para parametrizar o seu bloco de notas, selecione as reticências (...) para aceder a mais comandos na barra de ferramentas de células . Em seguida, selecione Alternar célula de parâmetro para designar a célula como a célula de parâmetros.

Azure Data Factory procura a célula de parâmetros e utiliza os valores como predefinições para os parâmetros transmitidos no momento da execução. O motor de execução adicionará uma nova célula abaixo da célula de parâmetros com parâmetros de entrada para substituir os valores predefinidos.

Atribuir valores de parâmetros a partir de um pipeline

Depois de criar um bloco de notas com parâmetros, pode executá-lo a partir de um pipeline com a atividade do bloco de notas do Synapse. Depois de adicionar a atividade à tela do pipeline, poderá definir os valores dos parâmetros na secção Parâmetros base no separador Definições .

Ao atribuir valores de parâmetros, pode utilizar a linguagem de expressão de pipeline ou as variáveis de sistema.

Ler o valor de saída da célula do bloco de notas do Synapse

Pode ler o valor de saída da célula do bloco de notas nas atividades seguintes ao seguir os passos abaixo:

Chame mssparkutils.notebook.exit API na sua atividade do bloco de notas do Synapse para devolver o valor que pretende mostrar na saída da atividade, por exemplo:
```
mssparkutils.notebook.exit("hello world") 
```
Ao guardar o conteúdo do bloco de notas e voltar a efetuar o pipeline, a saída da atividade do bloco de notas irá conter o exitValue que pode ser consumido para as seguintes atividades no passo 2.
Ler a propriedade exitValue a partir da saída da atividade do bloco de notas. Eis uma expressão de exemplo que é utilizada para verificar se o exitValue obtido a partir da saída da atividade do bloco de notas é igual a "hello world":

Executar outro bloco de notas do Synapse

Pode referenciar outros blocos de notas numa atividade de bloco de notas do Synapse através da chamada %run magic ou mssparkutils notebook utilities. Ambos suportam chamadas de função de aninhamento. As principais diferenças destes dois métodos que deve considerar com base no seu cenário são:

%run magic copie todas as células do bloco de notas referenciado para a célula %run e partilha o contexto da variável. Quando o bloco de notas1 referencia o bloco de notas2 via %run notebook2 e o bloco de notas2 chama uma função mssparkutils.notebook.exit , a execução de células no bloco de notas1 será interrompida. Recomendamos que utilize %run magic quando quiser "incluir" um ficheiro de bloco de notas.
Os utilitários do bloco de notas mssparkutils chamam o bloco de notas referenciado como um método ou uma função. O contexto da variável não é partilhado. Quando o bloco de notas1 referencia o bloco de notas2 via mssparkutils.notebook.run("notebook2") e o bloco de notas2 chama uma função mssparkutils.notebook.exit , a execução de células no bloco de notas1 continuará. Recomendamos que utilize utilitários de blocos de notas mssparkutils quando quiser "importar" um bloco de notas.

Ver histórico de execuções de atividades do bloco de notas

Aceda a Execuções de pipeline no separador Monitor . Verá o pipeline que acionou. Abra o pipeline que contém a atividade do bloco de notas para ver o histórico de execuções.

Pode ver o instantâneo de execução mais recente do bloco de notas, incluindo a entrada e a saída das células ao selecionar o botão abrir bloco de notas .

Captura de ecrã que mostra o histórico de atividades do bloco de notas.

Abra o instantâneo do bloco de notas:

Captura de ecrã que mostra um instantâneo de bloco de notas aberto.

Pode ver a entrada ou saída da atividade do bloco de notas ao selecionar o botão entrada ou Saída . Se o pipeline tiver falhado com um erro de utilizador, selecione a saída para verificar o campo de resultado para ver a análise detalhada de erros do utilizador.

Captura de ecrã que mostra os detalhes do erro do utilizador.

Definição de atividade do bloco de notas do Synapse

Eis a definição JSON de exemplo de uma atividade de bloco de notas do 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"
                }
            }
        }
    }
}

Saída da atividade do bloco de notas do Synapse

Eis o JSON de exemplo de uma saída de atividade do bloco de notas do 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 conhecidos

Se o nome do bloco de notas estiver parametrizado na atividade Bloco de Notas do Pipeline, a versão do bloco de notas no estado não publicado não pode ser referenciada nas execuções de depuração.