Condividi tramite

bundle gruppo di comandi

  • Articolo

Nota

Queste informazioni si applicano all'interfaccia della riga di comando di Databricks versione 0.205 e successive. L'interfaccia della riga di comando di Databricks è disponibile in anteprima pubblica.

L'uso dell'interfaccia della riga di comando di Databricks è soggetto all'Informativa sulla privacy di Databricks e databricks, incluse eventuali disposizioni sui dati di utilizzo.

Il gruppo di comandi bundle all'interno dell'interfaccia della riga di comando di Databricks consente di convalidare, distribuire ed eseguire flussi di lavoro di Azure Databricksa livello di codice, ad esempio processi di Azure Databricks, pipeline di tabelle live Delta e tack MLOps. Consultare Che cosa sono i Databricks Asset Bundle?.

I comandi bundle vengono eseguiti aggiungendoli a databricks bundle. Visualizza la guida relativa al comando bundle, eseguire databricks bundle -h.

Crea un bundle da un modello di progetto

Per creare un bundle di asset di Databricks usando il modello di bundle di asset di Databricks predefinito per Python, eseguire il bundle init comando come indicato di seguito e quindi rispondere alle richieste visualizzate:

databricks bundle init

Per creare un bundle di asset di Databricks usando un modello di bundle di asset di Databricks personalizzato, eseguire il bundle init comando come segue:

databricks bundle init <project-template-local-path-or-url> \
--project-dir="</local/path/to/project/template/output>"

Vedere anche:

Visualizzare lo schema di configurazione del bundle

Per visualizzare lo schema di configurazione del bundle, eseguire il bundle schema comando come segue:

databricks bundle schema

Per produrre lo schema di configurazione del bundle di asset Databricks come file JSON, eseguire il comando bundle schema e reindirizzare l'output a un file JSON. Ad esempio, si può generare un file denominato bundle_config_schema.json all'interno della directory corrente, come indicato di seguito:

databricks bundle schema > bundle_config_schema.json

Convalidare un bundle

Per verificare che i file di configurazione del bundle siano sintatticamente corretti, eseguire il comando bundle validatedalla radice del progetto bundle, come indicato di seguito:

databricks bundle validate

Per impostazione predefinita, questo comando fornisce un riepilogo dell'identità del bundle:

Name: MyBundle
Target: dev
Workspace:
  Host: https://my-host.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/MyBundle/dev

Validation OK!

Nota

Il comando bundle validate emette avvisi se nei file di configurazione del bundle sono definite proprietà di risorse che non si trovano nello schema dell'oggetto corrispondente.

Se si vuole solo restituire un riepilogo dell'identità e delle risorse del bundle, usare il riepilogo del bundle.

Sincronizzare l'albero di un bundle in un'area di lavoro

Usate il comando bundle sync per eseguire la sincronizzazione unidirezionale delle modifiche ai file di un bundle all'interno di una directory del sottosistema locale, verso una directory all'interno di un'area di lavoro remota di Azure Databricks.

Nota

I comandi bundle sync non possono sincronizzare le modifiche dei file da una directory all'interno di un'area di lavoro remota di Azure Databricks, in una directory all'interno di un sottosistema locale.

I comandi databricks bundle sync funzionano allo stesso modo dei comandi databricks synce vengono forniti come strumento di produttività. Per informazioni sull'utilizzo dei comandi, si veda Gruppo di comandi di sincronizzazione.

Generare un file di configurazione del bundle

È possibile usare il bundle generate comando per generare la configurazione delle risorse per un processo, una pipeline o un dashboard già esistente nell'area di lavoro di Databricks. Questo comando genera un *.yml file per il processo, la pipeline o il dashboard nella resources cartella del progetto bundle e scarica anche eventuali file, ad esempio notebook, a cui si fa riferimento nella configurazione.

Generare la configurazione del processo o della pipeline

Importante

Il comando bundle generate viene fornito per praticità per generare automaticamente la configurazione delle risorse. Tuttavia, quando questo processo o configurazione della pipeline viene incluso nel bundle e distribuito, crea una nuova risorsa e non aggiorna la risorsa esistente a meno che bundle deployment bind non sia stata usata per la prima volta. Vedere Associare le risorse del bundle.

Per generare la configurazione per un processo o una pipeline, eseguire il bundle generate comando come segue:

databricks bundle generate [job|pipeline] --existing-[job|pipeline]-id [job-id|pipeline-id]

Nota

Attualmente, solo i processi con attività di notebook sono supportati da questo comando.

Ad esempio, il seguente comando genera un nuovo file hello_job.ymlnella cartella resources del progetto bundle contenente il seguente file YAML e scarica simple_notebook.py nella cartella di progetto src.

databricks bundle generate job --existing-job-id 6565621249

# This is the contents of the resulting hello_job.yml file.
resources:
  jobs:
    6565621249:
      name: Hello Job
      format: MULTI_TASK
      tasks:
        - task_key: run_notebook
          existing_cluster_id: 0704-xxxxxx-yyyyyyy
          notebook_task:
            notebook_path: ./src/simple_notebook.py
            source: WORKSPACE
          run_if: ALL_SUCCESS
      max_concurrent_runs: 1

Generare la configurazione del dashboard

Per generare la configurazione per un dashboard esistente nell'area di lavoro, eseguire bundle generate, specificando l'ID o il percorso dell'area di lavoro per il dashboard:

databricks bundle generate dashboard --existing-id [dashboard-id]

databricks bundle generate dashboard --existing-path [dashboard-workspace-path]

È possibile copiare il percorso dell'area di lavoro per un dashboard dall'interfaccia utente dell'area di lavoro.

Ad esempio, il comando seguente genera un nuovo baby_gender_by_county.dashboard.yml file nella resources cartella del progetto bundle contenente il file YAML seguente e scarica il baby_gender_by_county.lvdash.json file nella cartella del src progetto.

databricks bundle generate dashboard --existing-path "/Workspace/Users/someone@example.com/baby_gender_by_county.lvdash.json"

# This is the contents of the resulting baby_gender_by_county.dashboard.yml file.
resources:
  dashboards:
    baby_gender_by_county:
      display_name: "Baby gender by county"
      warehouse_id: aae11o8e6fe9zz79
      file_path: ../src/baby_gender_by_county.lvdash.json

Suggerimento

Per aggiornare il .lvdash.json file dopo aver già distribuito un dashboard, usare l'opzione --resource quando si esegue bundle generate dashboard per generare tale file per la risorsa dashboard esistente. Per eseguire continuamente il polling e recuperare gli aggiornamenti in un dashboard, usare le --force opzioni e --watch .

Associare le risorse del bundle

Il comando bundle deployment bind consente di collegare processi e pipeline definiti in bundle a pipeline e processi esistenti nell'area di lavoro di Azure Databricks in modo che diventino gestiti da bundle di asset di Databricks. Se si associa una risorsa, le risorse di Azure Databricks esistenti nell'area di lavoro vengono aggiornate in base alla configurazione definita nel bundle a cui è associato dopo la successiva bundle deploy.

Suggerimento

È consigliabile confermare il bundle nell'area di lavoro prima di eseguire l'associazione.

databricks bundle deployment bind [resource-key] [resource-id]

Ad esempio, il seguente comando associa la risorsa hello_job alla controparte remota nell'area di lavoro. Il comando produce una differenza e consente di negare l'associazione delle risorse; tuttavia, se confermato, qualsiasi aggiornamento della definizione di processi nel bundle viene applicato al processo remoto corrispondente quando, successivamente, il bundle viene implementato.

databricks bundle deployment bind hello_job 6565621249

Usare bundle deployment unbind se si vuole rimuovere il collegamento tra il processo o la pipeline di un bundle e la relativa controparte remota in un'area di lavoro.

databricks bundle deployment unbind [resource-key]

Output di un riepilogo del bundle

Il bundle summary comando restituisce un riepilogo dell'identità e delle risorse di un bundle, inclusi collegamenti diretti per le risorse, in modo da poter passare facilmente alla risorsa nell'area di lavoro Databricks.

databricks bundle summary

L'output di esempio seguente è il riepilogo di un bundle denominato my_pipeline_bundle che definisce un processo e una pipeline:

Name: my_pipeline_bundle
Target: dev
Workspace:
  Host: https://myworkspace.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/my_pipeline/dev
Resources:
  Jobs:
    my_project_job:
      Name: [dev someone] my_project_job
      URL:  https://myworkspace.cloud.databricks.com/jobs/206000809187888?o=6051000018419999
  Pipelines:
    my_project_pipeline:
      Name: [dev someone] my_project_pipeline
      URL:  https://myworkspace.cloud.databricks.com/pipelines/7f559fd5-zztz-47fa-aa5c-c6bf034b4f58?o=6051000018419999

Suggerimento

È anche possibile usare bundle open per passare a una risorsa nell'area di lavoro databricks. Vedere Aprire una risorsa bundle.

Implementare un bundle

Per implementare un bundle nell'area di lavoro remota, eseguire il comando bundle deploy dalla radice del progetto bundle. Se non vengono specificate opzioni di comando, si utilizza la destinazione predefinita indicata nei file di configurazione del bundle.

databricks bundle deploy

Per implementare il bundle in una destinazione specifica, impostare l'opzione -t (o --target) insieme al nome della destinazione come indicato all'interno dei file di configurazione del bundle. Ad esempio, per una destinazione indicata con il nome dev:

databricks bundle deploy -t dev

Un bundle può essere implementato in più aree di lavoro, ad esempio sviluppo, gestione temporanea e aree di lavoro di produzione. Fondamentalmente, la proprietà root_path è ciò che determina l'identità univoca di un bundle, che per impostazione predefinita è ~/.bundle/${bundle.name}/${bundle.target}. Di conseguenza, per impostazione predefinita, l'identità di un bundle è costituita dall'identità del deployer, dal nome del bundle e dal nome di destinazione del bundle. Se questi sono identici in bundle diversi, la distribuzione di questi bundle interferisce tra loro.

Inoltre, l'implementazione di un bundle tiene traccia delle risorse create nell'area di lavoro di destinazione tramite i relativi ID, come stato memorizzato nel sottosistema dell'area di lavoro. I nomi delle risorse non vengono usati per correlare tra l’implementazione di bundle e un'istanza di risorsa, quindi:

  • Se una risorsa nella configurazione del bundle non esiste nell'area di lavoro di destinazione, viene creata.
  • Se una risorsa della configurazione del bundle è presente nell'area di lavoro di destinazione, viene aggiornata nell'area di lavoro.
  • Se una risorsa viene rimossa dalla configurazione del bundle, viene rimossa anche dall'area di lavoro di destinazione, se in precedenza vi era stata implementata.
  • L'associazione di una risorsa a un bundle può essere dimenticata solo se si modifica il nome del bundle, la destinazione del bundle o l'area di lavoro. È possibile eseguire bundle validate per ottenere un riepilogo contenente questi valori.

Eseguire un processo o una pipeline

Per eseguire un processo o una pipeline specifica, usare il comando bundle run. È necessario specificare la chiave di risorsa del processo o della pipeline indicata all'interno dei file di configurazione del bundle. Per impostazione predefinita, viene usato l'ambiente indicato all'interno dei file di configurazione del bundle. Ad esempio, per eseguire un processo hello_job nell'ambiente predefinito, eseguire il seguente comando:

databricks bundle run hello_job

Per eseguire un processo con una chiave hello_job nel contesto di una destinazione indicata con il nome dev:

databricks bundle run -t dev hello_job

Se si vuole eseguire una convalida della pipeline, usare l'opzione --validate-only, come illustrato nell'esempio seguente:

databricks bundle run --validate-only my_pipeline

Per passare i parametri del processo, usare l'opzione --params, seguita da coppie chiave-valore delimitate da virgole, in cui la chiave è il nome del parametro. Ad esempio, il seguente comando imposta il parametro con il nome message su HelloWorld per il processo hello_job:

databricks bundle run --params message=HelloWorld hello_job

Nota

È possibile passare parametri alle attività di processo usando le opzioni dell'attività di processo, ma l'opzione --params è il metodo consigliato per passare i parametri del processo. Si verifica un errore se si specificano parametri di processo per un processo che non ha parametri di processo definiti o se si specificano parametri di processo per un processo che ha parametri di processo definiti.

Per annullare e riavviare un aggiornamento di processo o pipeline esistente, usare l'opzione --restart:

databricks bundle run --restart hello_job

Aprire una risorsa bundle

Per passare a una risorsa bundle nell'area di lavoro, eseguire il bundle open comando dalla radice del progetto bundle, specificando la risorsa da aprire. Se non viene specificata una chiave di risorsa, questo comando restituisce un elenco delle risorse del bundle da cui scegliere.

databricks bundle open [resource-key]

Ad esempio, il comando seguente avvia un browser e passa al dashboard baby_gender_by_county nel bundle nell'area di lavoro Databricks configurata per il bundle:

databricks bundle open baby_gender_by_county

Eliminare definitivamente un bundle

Avviso

L'eliminazione definitiva di un bundle elimina definitivamente i processi, le pipeline e gli artefatti distribuiti in precedenza di un bundle. Questa azione non può essere annullata.

Per eliminare processi, pipeline e artefatti precedentemente implementati, eseguire il comando bundle destroy. Il seguente comando elimina tutti i processi, le pipeline e gli artefatti implementati in precedenza e definiti nei file di configurazione del bundle:

databricks bundle destroy

Nota

L'identità di un bundle è costituita dal nome del bundle, dalla destinazione del bundle e dall'area di lavoro. Se si è modificato uno di questi elementi e si tenta di eliminare definitivamente un bundle prima di implementarlo, si verificherà un errore.

Per impostazione predefinita, viene richiesto di confermare l'eliminazione permanente dei processi, delle pipeline e degli artefatti implementati in precedenza. Per ignorare questi prompt ed eseguire l'eliminazione permanente automatica, aggiungere l'opzione --auto-approve al comando bundle destroy.