CLI de execuções (herdada)

  • Artigo

Importante

Esta documentação foi desativada e pode não estar atualizada.

Essas informações se aplicam às versões herdadas da CLI do Databricks 0.18 e anteriores. O Databricks recomenda que você use a versão 0.205 da CLI do Databricks mais recente ou superior. Consulte O que é a CLI do Databricks?. Para localizar sua versão da CLI do Databricks, execute databricks -v.

Para migrar da CLI do Databricks versão 0.18 ou inferior para a CLI do Databricks versão 0.205 ou superior, consulte Migração da CLI do Databricks.

Para executar subcomandos da CLI de trabalhos do Databricks anexe-os a databricks runs. Para executar subcomandos da CLI de execuções de trabalhos do Databricks, anexe-os a databricks jobs. Para os subcomandos da CLI dos trabalhos do Databricks, consulte a CLI dos trabalhos. Juntos, esses subcomandos chamam a API de Trabalhos e a API de Trabalhos 2.0.

Importante

A CLI de trabalhos do Databricks oferece suporte a chamadas para duas versões da API REST de Trabalhos do Databricks: versões 2.1 e 2.0. (A funcionalidade de execuções de trabalho faz parte da API REST de Trabalhos.) A versão 2.1 adiciona suporte para orquestração de trabalhos com várias tarefas; consulte Agendar e orquestrar fluxos de trabalho e Atualizações da API de trabalhos 2.0 para 2.1. O Databricks recomenda que se chame a versão 2.1, a menos que haja scripts herdados que dependam da versão 2.0 e que não possam ser migrados.

A menos que especificado de outra forma, os comportamentos programáticos descritos neste artigo aplicam-se igualmente às versões 2.1 e 2.0.

Observação

Se você receber um erro de nível 500 ao fazer solicitações à CLI para a execução de trabalhos, o Databricks recomendará repetir as solicitações por até 10 minutos (com um intervalo mínimo de 30 segundos entre as novas tentativa).

Requisitos de chamada da API REST de Trabalhos 2.1

Para configurar a CLI de trabalhos do Databricks (e a CLI de trabalhos) para chamar a API REST de Trabalhos 2.1, faça o seguinte:

  1. Atualize a CLI para a versão 0.16.0 ou superior.

  2. Realize um dos seguintes procedimentos:

    • Execute o comando databricks jobs configure --version=2.1. Isso adiciona a configuração jobs-api-version = 2.1 ao arquivo ~/.databrickscfg no Unix, Linux, macOS ou %USERPROFILE%\.databrickscfg no Windows. Todos os subcomandos da CLI de trabalhos (e da CLI de trabalhos) chamarão a API REST de Trabalhos 2.1 por padrão.
    • Isso adiciona a configuração jobs-api-version = 2.1 ao arquivo ~/.databrickscfg no Unix, Linux ou macOS, ou %USERPROFILE%\.databrickscfg no Windows. Todos os subcomandos da CLI de trabalhos (e da CLI de trabalhos) chamarão a API REST de Trabalhos 2.1 por padrão.
    • Acrescente a opção --version=2.1 (por exemplo, databricks runs list --version=2.1) para instruir a CLI de trabalhos a chamar a API REST de Trabalhos 2.1 somente para essa chamada.

    Se você não tiver adotado nenhuma das ações anteriores, a CLI de trabalhos (e a CLI de trabalhos) chamarão a API REST de Trabalhos 2.0 por padrão.

Requisitos de chamada da API REST de Trabalhos 2.0

Para configurar a CLI de trabalhos do Databricks (e a CLI de trabalhos) para chamar a API REST de Trabalhos 2.0, faça o seguinte:

  • Use uma versão da CLI do Databricks abaixo de 0.16.0, ou
  • Atualize a CLI para a versão 0.16.0 ou superior e, em seguida, siga um destes procedimentos:
    • Execute o comando databricks jobs configure --version=2.0. Isso adiciona a configuração jobs-api-version = 2.0 ao arquivo ~/.databrickscfg no Unix, Linux, macOS ou %USERPROFILE%\.databrickscfg no Windows. Todos os subcomandos da CLI de trabalhos (e da CLI de trabalhos) chamarão a API REST de Trabalhos 2.0 por padrão.
    • Isso adiciona a configuração jobs-api-version = 2.0 ao arquivo ~/.databrickscfg no Unix, Linux ou macOS, ou %USERPROFILE%\.databrickscfg no Windows. Todos os subcomandos da CLI de trabalhos (e da CLI de trabalhos) chamarão a API REST de Trabalhos 2.0 por padrão.
    • Acrescente a opção --version=2.1 (por exemplo, databricks runs list --version=2.0) para instruir a CLI de trabalhos a chamar a API REST de Trabalhos 2.0 somente para essa chamada.

Se você não tiver adotado nenhuma das ações anteriores, a CLI de trabalhos (e a CLI de trabalhos) chamarão a API REST de Trabalhos 2.0 por padrão.

Subcomandos e uso geral

databricks runs --help

Usage: databricks runs [OPTIONS] COMMAND [ARGS]...

  Utility to interact with jobs runs.

Options:
  -v, --version   [VERSION]
  --debug         Debug mode. Shows full stack trace on error.
  --profile TEXT  CLI connection profile to use. The default profile is
                  "DEFAULT".

  -h, --help      Show this message and exit.

Commands:
  cancel      Cancels the specified run.
  get         Gets the metadata about a run in JSON form.
  get-output  Gets the output of a run.
  list        Lists job runs.
  submit      Submits a one-time run.

Cancelar uma execução

Para ver a documentação de uso, execute databricks runs cancel --help.

databricks runs cancel --run-id 119

{}

Obter informações sobre uma execução

Para ver a documentação de uso, execute databricks runs get --help.

Uso geral

databricks runs get --run-id 2785782

Notas de uso e exemplo de resposta da CLI de Trabalhos 2.1

Consulte Execuções obtidas na Atualização da API de Trabalhos 2.0 para 2.1.

Exemplo de resposta da CLI de Trabalhos 2.0

{
  "job_id": 1269263,
  "run_id": 2785782,
  "number_in_job": 1111,
  "original_attempt_run_id": 2785782,
  "state": {
    "life_cycle_state": "TERMINATED",
    "result_state": "SUCCESS",
    "state_message": ""
  },
  "task": {
    "notebook_task": {
      "notebook_path": "/Users/someone@example.com/notebooks/my-notebook.ipynb"
    }
  },
  "cluster_spec": {
    "new_cluster": {
      "spark_version": "8.1.x-scala2.12",
      "node_type_id": "Standard_F16s",
      "enable_elastic_disk": true,
      "azure_attributes": {
        "availability": "ON_DEMAND_AZURE"
      },
      "num_workers": 8
    }
  },
  "cluster_instance": {
    "cluster_id": "1234-567890-abcd123",
    "spark_context_id": "1234567890123456789"
  },
  "start_time": 1620947196985,
  "setup_duration": 36000,
  "execution_duration": 119000,
  "cleanup_duration": 3000,
  "end_time": 1620947355499,
  "trigger": "ONE_TIME",
  "creator_user_name": "someone@example.com",
  "run_name": "my-notebook-run",
  "run_page_url": "https://adb-1234567890123456.7.azuredatabricks.net/?o=1234567890123456#job/1269263/run/1111",
  "run_type": "JOB_RUN",
  "attempt_number": 0
}

Obter a saída de uma executar

Para ver a documentação de uso, execute databricks runs get-output --help.

Observação

Quando um notebook_task retorna um valor de uma chamada para dbutils.notebook.exit(), o Databricks limita o valor retornado aos primeiros 5 MB de dados. Para retornar um resultado maior, você pode armazenar os resultados do trabalho em um serviço de armazenamento em nuvem.

Uso geral

databricks runs get-output --run-id 2785782

Notas de uso da CLI de Trabalhos 2.1

Consulte Execuções de saída obtidas na Atualização da API de Trabalhos 2.0 para 2.1.

Exemplo de resposta da CLI de Trabalhos 2.0

{
  "metadata": {
    "job_id": 1269263,
    "run_id": 2785782,
    "number_in_job": 1111,
    "original_attempt_run_id": 2785782,
    "state": {
      "life_cycle_state": "TERMINATED",
      "result_state": "SUCCESS",
      "state_message": ""
    },
    "task": {
      "notebook_task": {
        "notebook_path": "/Users/someone@example.com/notebooks/my-notebook.ipynb"
      }
    },
    "cluster_spec": {
      "new_cluster": {
        "spark_version": "8.1.x-scala2.12",
        "node_type_id": "Standard_F16s",
        "enable_elastic_disk": true,
        "azure_attributes": {
          "availability": "ON_DEMAND_AZURE"
        },
        "num_workers": 8
      }
    },
    "cluster_instance": {
      "cluster_id": "1234-567890-abcd123",
      "spark_context_id": "1234567890123456789"
    },
    "start_time": 1620947196985,
    "setup_duration": 36000,
    "execution_duration": 119000,
    "cleanup_duration": 3000,
    "end_time": 1620947355499,
    "trigger": "ONE_TIME",
    "creator_user_name": "someone@example.com",
    "run_name": "my-notebook-run",
    "run_page_url": "https://adb-1234567890123456.7.azuredatabricks.net/?o=1234567890123456#job/1269263/run/1111",
    "run_type": "JOB_RUN",
    "attempt_number": 0
  },
  "notebook_output": {}
}

Obter informações sobre todas as execuções

Para ver a documentação de uso, execute databricks runs list --help.

Uso geral

databricks runs list --output JSON

Notas de uso e exemplo de resposta da CLI de Trabalhos 2.1

Consulte a Lista de execuções na Atualização da API de Trabalhos 2.0 para 2.1.

Exemplo de resposta da CLI de Trabalhos 2.0

{
  "runs": [
    {
      "job_id": 1269263,
      "run_id": 2785782,
      "number_in_job": 1111,
      "original_attempt_run_id": 2785782,
      "state": {
         "life_cycle_state": "TERMINATED",
         "result_state": "SUCCESS",
         "state_message": ""
      },
      "task": {
        "notebook_task": {
          "notebook_path": "/Users/someone@example.com/notebooks/my-notebook.ipynb"
        }
      },
      "cluster_spec": {
        "new_cluster": {
          "spark_version": "8.1.x-scala2.12",
          "node_type_id": "Standard_F16s",
          "enable_elastic_disk": true,
          "azure_attributes": {
            "availability": "ON_DEMAND_AZURE"
          },
          "num_workers": 8
        }
      },
      "cluster_instance": {
        "cluster_id": "1234-567890-abcd123",
        "spark_context_id": "1234567890123456789"
      },
      "start_time": 1620947196985,
      "setup_duration": 36000,
      "execution_duration": 119000,
      "cleanup_duration": 3000,
      "end_time": 1620947355499,
      "trigger": "ONE_TIME",
      "creator_user_name": "someone@example.com",
      "run_name": "my-notebook-run",
      "run_page_url": "https://adb-1234567890123456.7.azuredatabricks.net/?o=1234567890123456#job/1269263/run/1111",
      "run_type": "JOB_RUN",
      "attempt_number": 0
    },
    ...
  ],
  "has_more": false
}

Se has_more retornar true, as informações sobre as outras execuções estarão disponíveis. Use a opção --offset para retornar informações sobre as execuções em relação à última. Por exemplo, para retornar informações começando com a 10ª versão mais recente, especifique --offset 10.

Use a opção --limit para retornar informações sobre um número fixo de execuções. Por exemplo, para retornar informações para até as próximas 5 execuções, especifique --limit 5. Você pode especificar até 1000 execuções. Se não for especificado, o padrão será 20.

Enviar uma única execução

Para ver a documentação de uso, execute databricks runs submit --help.

Uso geral

databricks runs submit --json-file submit-run.json

Notas de uso e exemplo de solicitação da API REST de Trabalhos 2.1

Consulte Execuções enviadas em Atualização da API de Trabalhos 2.0 para 2.1.

Exemplo de solicitação e resposta da API REST de Trabalhos 2.0

submit-run.json:

{
  "run_name": "my-spark-run",
  "new_cluster": {
    "spark_version": "8.1.x-scala2.12",
    "node_type_id": "Standard_F16s",
    "enable_elastic_disk": true,
    "azure_attributes": {
      "availability": "ON_DEMAND_AZURE"
    },
    "num_workers": 8
  },
  "libraries": [
    {
      "jar": "dbfs:/my-jar.jar"
    },
    {
      "maven": {
        "coordinates": "org.jsoup:jsoup:1.7.2"
      }
    }
  ],
  "spark_jar_task": {
    "main_class_name": "com.databricks.ComputeModels"
  }
}

{
  "run_id": 123
}