Configurar as versões do ambiente nos pipelines

Importante

As versões de ambiente para os oleodutos Lakeflow estão em Pré-visualização Pública.

Uma versão de ambiente define a versão da linguagem Python e o conjunto de bibliotecas Python pré-instaladas disponível para o código Python do seu pipeline. Quaisquer dependências externas que adicionar ao pipeline são adicionadas sobre esta base.

As versões do ambiente desvinculam o ambiente de execução Python do seu pipeline da versão do Databricks Runtime em que o pipeline é executado. Enquanto uma versão do ambiente está definida, as atualizações do Databricks em tempo de execução não alteram a versão da tua linguagem Python nem as versões pré-instaladas da biblioteca. O runtime de Python também é compatível com tarefas sem servidor e notebooks que usam a mesma versão do ambiente. Para encontrar a versão atual do Databricks Runtime para pipelines do Lakeflow, consulte as notas de versão dos pipelines do Lakeflow e o processo de atualização da versão.

A Databricks migra automaticamente os pipelines elegíveis para uma versão de ambiente. Ver Migração automática.

Importante

As pipelines com uma versão de ambiente executam código Python através do Spark Connect, o que pode alterar o comportamento de algum código da pipeline. Para a lista completa de limitações e alterações de comportamento, veja Compatibilidade de versões do Ambiente.

Requirements

As versões do ambiente têm os seguintes requisitos:

  • O pipeline deve usar o Unity Catalog. Os pipelines do metastore do Hive não são suportados.

Versões suportadas do ambiente

Os pipelines Lakeflow suportam as versões 3 e 4 do ambiente tanto em computação serverless como clássica. Para a versão da linguagem Python e a lista completa de bibliotecas Python pré-instaladas disponíveis em cada versão, consulte a referência da versão do ambiente.

Migração automática

O Databricks migra automaticamente os pipelines elegíveis para uma versão do ambiente. A migração ocorre na próxima atualização de um pipeline, não requer passos manuais e inclui estas salvaguardas:

  • O comportamento é verificado antes da migração. O Databricks analisa o seu pipeline à procura de padrões de código que se comportariam de forma diferente no Spark Connect e compara o plano de saída do pipeline antes e depois da migração. Consulte compatibilidade de versões do ambiente.
  • Uma migração falhada reverte automaticamente. Se uma atualização migrada falhar por qualquer motivo, é interrompida antes de qualquer dado ser escrito, e o pipeline reverte automaticamente ao seu tempo de execução anterior na atualização seguinte. Não é necessária qualquer ação.
  • As tuas definições explícitas são sempre respeitadas. Se definires environment_version manualmente, o Databricks nunca o substitui.

Uma vez que um pipeline migra com sucesso, corre na versão de ambiente daqui para a frente. Pode ver a versão selecionada nas definições do pipeline, a GetPipeline resposta da API e o runtime_details registo de eventos.

O que não é migrado automaticamente

Uma canalização não é migrada automaticamente se se verificar qualquer uma das seguintes condições:

Os pipelines que não são migrados automaticamente continuam a correr no runtime anterior do Python, sem qualquer alteração. Pode ativar uma versão do ambiente por si quando o pipeline estiver elegível.

Ativa tu mesmo uma versão do ambiente

A migração automática cobre a maioria dos pipelines. Também pode configurar explicitamente uma versão do ambiente, por exemplo, para migrar mais cedo ou fixar uma versão específica, através da interface do editor de pipelines, da API REST do Pipelines ou dos Pacotes de Automação Declarativa.

Antes de ativares explicitamente uma versão do ambiente, verifica se o teu pipeline é compatível com o Spark Connect. Se o Databricks detetar que a ativação da versão alteraria o comportamento do seu pipeline, a atualização falha antes de quaisquer dados serem escritos, sendo apresentado um erro que identifica a diferença a resolver.

Ativar através da interface de utilizador

  1. No editor de pipeline, clique em Configurações.
  2. Em Ambiente do pipeline, selecione o ícone de lápis.Editar ambiente.
  3. Selecione uma versão do ambiente na lista suspensa.
  4. Guarda as definições do pipeline.

As dependências externas adicionadas na secção Ambiente de Pipeline são sobrepostas às bibliotecas incluídas na versão selecionada do ambiente. Consulte Gerenciar dependências Python para pipelines.

Ativar através da API

A API REST de Pipelines aceita um bloco environment na criação e atualização de pipelines. A autenticação por Token de Acesso Pessoal deve estar ativada para o espaço de trabalho.

Para criar um pipeline com uma versão do ambiente:

curl --request POST \
  --url 'https://<workspace-host>/api/2.0/pipelines' \
  --header 'Authorization: Bearer <personal-access-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<pipeline-name>",
    "catalog": "<catalog>",
    "schema": "<schema>",
    "channel": "CURRENT",
    "environment": {
      "environment_version": "4",
      "dependencies": [
        "simplejson==3.19.*"
      ]
    }
  }'

Para definir a versão do ambiente num pipeline existente, envie o mesmo environment bloco com PUT /api/2.0/pipelines/<pipeline-id>.

Ativar através de Pacotes de Automação Declarativa

Quando cria um pipeline usando Declarative Automation Bundles, pode definir uma versão do ambiente na definição YAML do pipeline.

  1. Certifica-te de que a tua CLI Databricks está na versão v0.294.0 ou posterior. Se não, atualize seguindo o guia de instalação.
  2. Configurar um pacote seguindo o tutorial sobre pacotes de pipelines.
  3. Localize o ficheiro YAML do pipeline no seu pacote, normalmente em <bundle-folder>/resources/<pipeline_name>_pipeline.yml.
  4. Defina os campos environment_version e dependencies no YAML do pipeline:
resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      catalog: ${var.catalog}
      schema: ${var.schema}
      root_path: '../src/my_pipeline'
      libraries:
        - glob:
            include: ../src/my_pipeline/transformations/**
      environment:
        environment_version: 4
        dependencies:
          - --editable ${workspace.file_path}

Verifique a versão do ambiente num pipeline

Para verificar qual a versão do ambiente que um pipeline está a correr, se o define explicitamente ou se o Databricks o selecionou durante a migração automática:

  • UI: Abra as definições do pipeline e verifique a secção Ambiente do pipeline, ou inspecione o painel JSON para o campo environment.environment_version.
  • API: Ligue GET /api/2.0/pipelines/<pipeline-id> e procure environment.environment_version na resposta. Isto mostra uma versão que definiste explicitamente; Para ver uma versão selecionada pela migração automática, utilize o registo de eventos abaixo.
  • Registo de eventos: Inspecionar o runtime_details evento, que reporta a versão do ambiente usada na atualização. Ver detalhes do evento runtime_details.

Desativar ou reverter uma versão do ambiente

Não precisas de reverter manualmente uma migração automática. Uma migração que falha é automaticamente revertida na próxima atualização. Quando a versão do ambiente é removida, o pipeline regressa à sua configuração anterior em tempo de execução em Python. Se acontecer algo inesperado, contacte o suporte do Azure Databricks.

Recursos adicionais

  • Last updated on