Transformar dados executando um bloco de notas Synapse

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

A atividade do caderno Azure Synapse numa pipeline Synapse executa um caderno Synapse. Este artigo baseia-se no artigo de atividades de transformação de dados, que apresenta uma visão geral da transformação de dados e das atividades de transformação suportadas.

Criar uma atividade do bloco de anotações Synapse

Você pode criar uma atividade de notebook Synapse diretamente a partir do painel do pipeline Synapse ou do editor de notebook. A atividade do notebook Synapse é executada no pool Spark que é escolhido no notebook Synapse.

Adicionar uma atividade de notebook Synapse no espaço de trabalho do pipeline

Arraste e solte o notebook Synapse debaixo de Atividades no canvas do pipeline Synapse. Selecione a caixa de atividade do bloco de anotações Synapse e configure o conteúdo do bloco de anotações para a atividade atual nas configurações. Você pode selecionar um bloco de anotações existente no espaço de trabalho atual ou adicionar um novo.

Se você selecionar um bloco de anotações existente no espaço de trabalho atual, poderá clicar no botão Abrir para abrir diretamente a página do bloco de anotações.

(Opcional) Você também pode reconfigurar o pool do Spark\Tamanho do executor\Alocar executores dinamicamente\Executores mínimos\Executores máximos\Tamanho do driver\Autenticação nas definições. Deve-se notar que as configurações reconfiguradas aqui substituirão as configurações da sessão de configuração no Notebook. Se nada estiver definido nas configurações da atividade atual do bloco de anotações, a atividade será executada com as configurações da sessão de configuração desse bloco de anotações.

Adicionar um bloco de anotações ao pipeline Synapse

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

Parâmetros de passagem

Designar uma célula de parâmetros

Para parametrizar seu bloco de anotações, selecione as reticências (...) para acessar mais comandos na barra de ferramentas da célula. Em seguida, selecione Alternar célula de parâmetro para designar a célula como a célula de parâmetros.

Defina seus parâmetros nesta célula. Pode ser algo tão simples como:

a = 1
b = 3
c = "Default Value"

Você pode fazer referência a esses parâmetros em outras células e, ao executar o bloco de anotações, usar os valores padrão especificados na célula de parâmetros.

Quando executa este bloco de notas a partir de um pipeline, o Azure Data Factory procura a célula de parâmetros e utiliza os valores fornecidos como predefinições para os parâmetros passados em tempo de execução. Se você atribuir valores de parâmetros de um pipeline, o mecanismo de execução adicionará uma nova célula abaixo da célula de parâmetros com parâmetros de entrada para substituir os valores padrão.

Atribuir valores aos parâmetros de um pipeline

Depois de criar um notebook com parâmetros, pode executá-lo a partir de um pipeline com a atividade de notebook do Synapse. Depois de adicionares a atividade à tela do pipeline, poderás definir os valores dos parâmetros básicos na seção Parâmetros básicos no separador Configurações.

Depois de adicionar os parâmetros à atividade, o Data Factory passará os valores especificados na atividade para o bloco de anotações e o bloco de anotações será executado com esses novos valores de parâmetro, em vez dos padrões especificados na célula de parâmetros.

Ao atribuir valores de parâmetro, você pode usar a linguagem de expressão de pipeline ou variáveis de sistema.

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

Você pode ler o valor de saída da célula do notebook nas próximas atividades seguindo as etapas abaixo:

1. Chame a API mssparkutils.notebook.exit na atividade do notebook Synapse para retornar o valor que deseja mostrar na saída da atividade, por exemplo:

   mssparkutils.notebook.exit("hello world") 
   

   Salvando o conteúdo do bloco de anotações e acionando novamente o pipeline, a saída da atividade do bloco de anotações conterá o exitValue que pode ser consumido para as seguintes atividades na etapa 2.

2. Leia a propriedade exitValue da saída da atividade do bloco de anotações. Aqui está um exemplo de expressão que é usado para verificar se o exitValue obtido da saída da atividade do notebook é igual a "hello world":

   

Executar outro bloco de anotações Synapse

Você pode referenciar outros cadernos numa atividade de caderno Synapse chamando %run magic ou as utilidades de caderno mssparkutils. Ambos suportam chamadas de função de aninhamento. As principais diferenças desses dois métodos que você deve considerar com base no seu cenário são:

• %run magic copia todas as células do bloco de anotações referenciado para a célula %run e compartilha o contexto da variável. Quando notebook1 faz referência a notebook2 via %run notebook2 e notebook2 chama uma função mssparkutils.notebook.exit , a execução da célula no notebook1 será interrompida. Recomendamos que você use %run magic quando quiser "incluir" um arquivo de bloco de anotações.
• mssparkutils notebook utilities chama o notebook referenciado como um método ou uma função. O contexto da variável não é compartilhado. Quando notebook1 faz referência a notebook2 via mssparkutils.notebook.run("notebook2") e notebook2 chama uma função mssparkutils.notebook.exit , a execução da célula no notebook1 continuará. Recomendamos que você use os utilitários de notebook mssparkutils quando quiser "importar" um notebook.

Ver histórico de execução de atividades do bloco de notas

Vá para Pipeline executa na guia Monitor , você verá o pipeline que você acionou. Abra o pipeline que contém a atividade do notebook para ver o histórico de execução.

Você pode ver o instantâneo mais recente da execução do notebook, incluindo a entrada e a saída das células, selecionando o botão abrir bloco de anotações.

Abrir visualização do bloco de notas:

Você pode ver a entrada ou saída da atividade do notebook selecionando o botão de entrada ou Saída . Se o pipeline falhou com um erro de utilizador, selecione a saída para verificar o campo de resultado e ver o rastreio detalhado do erro de utilizador.

Definição de atividade do notebook Synapse

Aqui está a definição JSON de exemplo de uma atividade de bloco de anotações Sinapse:

{
    "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 de atividade do notebook Synapse

Aqui está o exemplo JSON de uma saída de atividade do bloco de anotações Sinapse:

{
{
    "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 anotações estiver parametrizado na atividade Pipeline Notebook, a versão do bloco de anotações em status não publicado não poderá ser referenciada nas execuções de depuração.