Configurare le versioni dell'ambiente per le pipeline

Una versione dell'ambiente fissa la versione del linguaggio Python e l'insieme di librerie Python preinstallate a disposizione del codice Python della pipeline. Tutte le dipendenze esterne aggiunte alla pipeline vengono sovrapposte a questa base.

Le versioni dell'ambiente separano il runtime di Python della pipeline dalla versione di Databricks Runtime in cui viene eseguita la pipeline. Mentre è impostata una versione dell'ambiente, gli aggiornamenti di Databricks Runtime non modificano la versione della lingua Python o le versioni della libreria preinstallate. Il runtime Python è compatibile anche con job serverless e notebook che utilizzano la stessa versione dell'ambiente. Per trovare la versione corrente di Databricks Runtime per le pipeline Lakeflow, vedere Le note sulla versione delle pipeline di Lakeflow e il processo di aggiornamento della versione.

Databricks migra automaticamente le pipeline idonee su una versione dell'ambiente. Vedi Migrazione automatica.

Requisiti

Le versioni dell'ambiente hanno i requisiti seguenti:

• La pipeline deve utilizzare Unity Catalog. Le pipeline del metastore Hive non sono supportate.

Versioni dell'ambiente supportate

Le pipeline di Lakeflow supportano le versioni dell'ambiente 3 e 4 sia nel calcolo serverless che in quello classico. Per la versione del linguaggio Python e l'elenco completo delle librerie Python preinstallate disponibili in ogni versione, consulta il riferimento alla versione dell'ambiente.

Migrazione automatica

Databricks migra automaticamente le pipeline idonee su una versione dell'ambiente. La migrazione avviene al prossimo aggiornamento di una pipeline, non richiede passaggi manuali e include queste salvaguardie:

• Il comportamento viene controllato prima della migrazione. Databricks scansiona la tua pipeline alla ricerca di pattern di codice che si comporterebbero diversamente sotto Spark Connect e confronta il piano di output della pipeline prima e dopo la migrazione. Vedi Compatibilità della versione dell'ambiente.
• Una migrazione non riuscita viene automaticamente ripristinata. Se un aggiornamento migrato fallisce per qualsiasi motivo, viene fermato prima che vengano scritti i dati e la pipeline torna automaticamente al suo runtime precedente al prossimo aggiornamento. Non è necessaria alcuna azione.
• Le tue impostazioni esplicite sono sempre rispettate. Se imposti manualmente environment_version, Databricks non lo sovrascrive mai.

Una volta che una pipeline viene migrata correttamente, verrà eseguita sulla versione dell'ambiente anche in seguito. Puoi vedere la versione selezionata nelle impostazioni della pipeline, la GetPipeline risposta API e il runtime_details registro eventi.

Cosa non viene migrato automaticamente

Una pipeline non viene migrata automaticamente se si applica una delle seguenti condizioni:

• Presenta avvisi di compatibilità di Spark Connect irrisolti derivanti dal suo aggiornamento più recente.
• Non è una pipeline di Unity Catalog.
• Utilizza una funzione che la migrazione automatica non copre ancora: foreach_batch sink,event hook, AUTO CDC da una funzione snapshot sorgente o un'immagine personalizzata.

Le pipeline che non vengono migrate continuano automaticamente a funzionare sul loro precedente runtime Python senza alcuna modifica. Puoi abilitare autonomamente una versione dell'ambiente una volta che la pipeline è idonea.

Abilita tu stesso una versione dell'ambiente

La migrazione automatica copre la maggior parte delle pipeline. Puoi anche configurare esplicitamente una versione dell'ambiente, ad esempio per migrare prima o per fissare una versione specifica, tramite l'interfaccia dell'editor di pipeline, l'API REST di Pipelines o i Declarative Automation Bundles.

Prima di abilitare esplicitamente una versione dell'ambiente, verifica che la tua pipeline sia compatibile con Spark Connect. Se Databricks rileva che abilitare la versione cambierebbe il comportamento della pipeline, l'aggiornamento fallisce prima che vengano scritti i dati, con un errore che identifica la differenza da risolvere.

Abilitare tramite l'interfaccia utente

1. Nell'editor della pipeline fare clic su Impostazioni.
2. In Ambiente pipeline selezionare Modificare l'ambiente.
3. Selezionare una versione dell'ambiente dall'elenco a discesa.
4. Salvare le impostazioni della pipeline.

Le dipendenze esterne aggiunte nella sezione Ambiente pipeline vengono sovrapposte alle librerie incluse nella versione dell'ambiente selezionata. Consulta Gestione delle dipendenze Python per le pipeline.

Abilitare tramite l'API

L'API REST Pipelines accetta un environment blocco per la creazione e l'aggiornamento della pipeline. L'autenticazione del token di accesso personale deve essere abilitata per l'area di lavoro.

Per creare una pipeline con una versione dell'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.*"
      ]
    }
  }'

Per impostare la versione dell'ambiente in una pipeline esistente, inviare lo stesso environment blocco con PUT /api/2.0/pipelines/<pipeline-id>.

Abilitazione tramite pacchetti di automazione dichiarativa

Quando si crea una pipeline usando bundle di automazione dichiarativa, è possibile impostare una versione dell'ambiente nella definizione YAML della pipeline.

1. Assicurarsi che l'interfaccia della riga di comando di Databricks sia disponibile nella versione 0.294.0 o successiva. In caso contrario, eseguire l'aggiornamento seguendo la guida all'installazione.
2. Configura un bundle seguendo il tutorial del bundle delle pipeline.
3. Individua il file YAML della pipeline nel bundle, in genere <bundle-folder>/resources/<pipeline_name>_pipeline.yml.
4. Imposta i campi environment_version e dependencies nella pipeline YAML:

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}

Verificare la versione dell'ambiente in una pipeline

Per verificare quale versione dell'ambiente una pipeline sta eseguendo, se la impostate esplicitamente o Databricks l'abbia selezionata durante la migrazione automatica:

• Interfaccia utente: aprire le impostazioni della pipeline e controllare la sezione Ambiente pipeline oppure esaminare il riquadro JSON per il environment.environment_version campo.
• API: chiamare GET /api/2.0/pipelines/<pipeline-id> e cercare environment.environment_version nella risposta. Questo mostra una versione che hai impostato esplicitamente; Per vedere una versione selezionata tramite migrazione automatica, utilizza il registro eventi qui sotto.
• Registro eventi: Ispezionare l'evento runtime_details , che riporta la versione dell'ambiente utilizzata per l'aggiornamento. Vedi i dettagli dell'evento runtime_details.

Disabilita o torna indietro una versione dell'ambiente

Non è necessario annullare manualmente una migrazione automatica. Una migrazione che fallisce viene automaticamente annullata al prossimo aggiornamento. Quando la versione dell'ambiente viene rimossa, la pipeline torna alla configurazione di runtime Python precedente. Se succede qualcosa di imprevisto, contatta il supporto Azure Databricks.

Risorse aggiuntive

• Compatibilità delle versioni dell'ambiente — limitazioni, cambiamenti comportamentali, scansione di compatibilità e migrazione automatica.
• Gestisci le dipendenze Python per le pipeline — ovvero dipendenze Python esterne sovrapposte a una versione dell'ambiente.