API de Trabalhos 2.0

  • Artigo

Importante

Este artigo documenta a versão 2.0 da API de Jobs. Entretanto, o Databricks recomenda utilizar a API de Trabalho 2.1 para clientes e scripts novos e existentes. Para obter detalhes sobre as alterações das versões 2.0 para 2.1, consulte Atualizações da API de Trabalhos 2.0 para 2.1.

A API de Trabalhos permite que você crie, edite e exclua trabalhos. O tamanho máximo permitido de uma solicitação na API de Trabalhos é de 10 MB.

Para obter detalhes sobre as atualizações da API de trabalhos que dão suporte à orquestração de várias tarefas com trabalhos do Azure Databricks, consulte Atualizações da API de trabalhos 2.0 para a 2.1.

Aviso

Você nunca deve codificar segredos ou armazená-los em texto sem formatação. Use a API de Segredos para gerenciar segredos na CLI do Databricks. Para referenciar segredos em notebooks e trabalhos, use o Utilitário de segredos (dbutils.secrets).

Observação

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

Importante

Para acessar as APIs REST do Databricks, é necessário autenticar-se.

Criar

Ponto de extremidade Método HTTP
2.0/jobs/create POST

Criar um novo trabalho.

Exemplo

Este exemplo cria um trabalho que executa uma tarefa JAR às 22:15 todas as noites.

Solicitação

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/create \
--data @create-job.json \
| jq .

create-job.json:

{
  "name": "Nightly model training",
  "new_cluster": {
    "spark_version": "7.3.x-scala2.12",
    "node_type_id": "Standard_D3_v2",
    "num_workers": 10
  },
  "libraries": [
    {
      "jar": "dbfs:/my-jar.jar"
    },
    {
      "maven": {
        "coordinates": "org.jsoup:jsoup:1.7.2"
      }
    }
  ],
  "timeout_seconds": 3600,
  "max_retries": 1,
  "schedule": {
    "quartz_cron_expression": "0 15 22 * * ?",
    "timezone_id": "America/Los_Angeles"
  },
  "spark_jar_task": {
    "main_class_name": "com.databricks.ComputeModels"
  }
}

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • O conteúdo de create-job.json com campos apropriados para sua solução.

Este exemplo usa um arquivo .netrc e jq.

Resposta

{
  "job_id": 1
}

Estrutura de solicitação

Importante

  • Quando você executa um trabalho em um novo cluster de trabalhos, ele será tratado como uma carga de trabalho Computação de Trabalhos (automatizada) sujeita aos preços da Computação de Trabalhos.
  • Quando você executa um trabalho em um cluster de uso geral existente, ele é tratado como uma carga de trabalho Computação para Todas as Finalidades (interativa) sujeita aos preços da Computação para Todas as Finalidades.
Nome do campo Tipo Descrição
existing_cluster_id OU new_cluster STRING OU NewCluster Se for existing_cluster_id, será o ID de um cluster existente que será usado para todas as execuções desse trabalho. Ao executar trabalhos em um cluster existente, talvez seja necessário reiniciar manualmente o cluster caso ele pare de responder. Sugerimos a execução de trabalhos em novos clusters para maior confiabilidade.

Se for new_cluster, será uma descrição de um cluster que será criado para cada execução.

Se você estiver especificando uma PipelineTask, esse campo poderá ficar vazio.
notebook_task OU spark_jar_task OU
spark_python_task OU spark_submit_task OU
pipeline_task OU run_job_task		 NotebookTask OU SparkJarTask OU SparkPythonTask OU SparkSubmitTask OU PipelineTask OU RunJobTask Se for notebook_task, isso indicará que esse trabalho deve executar um notebook. Esse campo não pode ser especificado em conjunto com spark_jar_task.

Se for spark_jar_task, isso indicará que esse trabalho deve executar um JAR.

Se for spark_python_task, isso indicará que esse trabalho deve executar um arquivo Python.

Se for spark_submit_task, isso indicará que esse trabalho deve ser lançado pelo script de envio do Spark.

Se for pipeline_task, isso indicará que esse trabalho deve executar um pipeline do Delta Live Tables.

Se for run_job_task, isso indica que esse trabalho deve executar outro trabalho.
name STRING Um nome opcional para o trabalho. O valor padrão é Untitled.
libraries Uma matriz de Biblioteca Uma lista opcional de bibliotecas a serem instaladas no cluster que executará o trabalho. O valor padrão é uma lista vazia.
email_notifications JobEmailNotifications Um conjunto opcional de endereços de email notificados quando as execuções desse trabalho começam e são concluídas e quando esse trabalho é excluído. O comportamento padrão é não enviar emails.
webhook_notifications WebhookNotifications Um conjunto opcional de destinos do sistema para notificar quando as execuções deste trabalho começam, são concluídas ou falham.
notification_settings JobNotificationSettings Configurações de notificação opcionais que são usadas ao enviar notificações para cada um dos email_notifications e webhook_notifications para esse trabalho.
timeout_seconds INT32 Um tempo limite opcional aplicado a cada execução desse trabalho. O comportamento padrão é sem tempo limite.
max_retries INT32 Um número máximo opcional de repetições de uma tentativa malsucedida. Uma execução será considerada malsucedida se for concluída com o result_state FAILED ou
INTERNAL_ERROR
life_cycle_state. O valor -1 significa novas tentativas indefinidamente; o valor 0 significa nunca tentar novamente. O comportamento padrão é nunca tentar novamente.
min_retry_interval_millis INT32 Um intervalo mínimo opcional em milissegundos entre o início da operação com falha e a execução da tentativa subsequente. O comportamento padrão é que as execuções malsucedidas sejam imediatamente tentadas novamente.
retry_on_timeout BOOL Uma política opcional para especificar se deve haver nova tentativa de um trabalho quando ele atinge o tempo limite. O comportamento padrão é não tentar novamente no tempo limite.
schedule CronSchedule Um agendamento periódico opcional para esse trabalho. O comportamento padrão é o trabalho ser executado quando disparado pelo clique em Executar Agora na interface do usuário Trabalhos ou pelo envio de uma solicitação de API a runNow.
max_concurrent_runs INT32 Um número máximo permitido opcional de execuções simultâneas do trabalho.

Defina esse valor se você quiser ser capaz de fazer várias execuções do mesmo trabalho simultaneamente. Isso é útil, por exemplo, se você dispara seu trabalho em um agendamento frequente e quer permitir que as execuções consecutivas se sobreponham ou se quer disparar várias execuções que tenham diferença nos parâmetros de entrada.

Essa configuração afeta somente novas execuções. Por exemplo, digamos que a simultaneidade do trabalho seja quatro e existem quatro execuções ativas simultâneas. A definição da simultaneidade como 3 não desativará nenhuma das execuções ativas. No entanto, a partir daí, novas execuções serão ignoradas, a menos que haja menos de três execuções ativas.

O valor não pode exceder 1000. A definição desse valor como 0 faz com que todas as novas execuções sejam ignoradas. O comportamento padrão é permitir apenas uma execução simultânea.

Estrutura de resposta

Nome do campo Tipo Descrição
job_id INT64 O identificador canônico do trabalho recém-criado.

Lista

Ponto de extremidade Método HTTP
2.0/jobs/list GET

Liste todos os trabalhos.

Exemplo

Solicitação

curl --netrc --request GET \
https://<databricks-instance>/api/2.0/jobs/list \
| jq .

Substitua <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.

Este exemplo usa um arquivo .netrc e jq.

Resposta

{
  "jobs": [
    {
      "job_id": 1,
      "settings": {
        "name": "Nightly model training",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "Standard_D3_v2",
          "num_workers": 10
        },
        "libraries": [
          {
            "jar": "dbfs:/my-jar.jar"
          },
          {
            "maven": {
              "coordinates": "org.jsoup:jsoup:1.7.2"
            }
          }
        ],
        "timeout_seconds": 100000000,
        "max_retries": 1,
        "schedule": {
          "quartz_cron_expression": "0 15 22 * * ?",
          "timezone_id": "America/Los_Angeles",
          "pause_status": "UNPAUSED"
        },
        "spark_jar_task": {
          "main_class_name": "com.databricks.ComputeModels"
        }
      },
      "created_time": 1457570074236
    }
  ]
}

Estrutura de resposta

Nome do campo Tipo Descrição
jobs Uma matriz de Trabalho A lista de trabalhos.

Excluir

Ponto de extremidade Método HTTP
2.0/jobs/delete POST

Exclua um trabalho e envie um email aos endereços especificados em JobSettings.email_notifications. Nenhuma ação ocorrerá se o trabalho já tiver sido removido. Depois que o trabalho for removido, seus detalhes e seu histórico de execução deixarão de ficar visíveis na interface do usuário Trabalhos ou na API. É garantido que o trabalho será removido após a conclusão dessa solicitação. No entanto, as execuções que estavam ativas antes do recebimento dessa solicitação ainda poderão estar ativas. Elas serão terminadas de forma assíncrona.

Exemplo

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/delete \
--data '{ "job_id": <job-id> }'

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • <job-id> com o ID do trabalho, por exemplo, 123.

Este exemplo usa um arquivo .netrc.

Estrutura de solicitação

Nome do campo Tipo Descrição
job_id INT64 O identificador canônico do trabalho a ser excluído. Esse campo é obrigatório.

Get

Ponto de extremidade Método HTTP
2.0/jobs/get GET

Recuperar informações sobre um único trabalho.

Exemplo

Solicitação

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/jobs/get?job_id=<job-id>' \
| jq .

Ou:

curl --netrc --get \
https://<databricks-instance>/api/2.0/jobs/get \
--data job_id=<job-id> \
| jq .

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • <job-id> com o ID do trabalho, por exemplo, 123.

Este exemplo usa um arquivo .netrc e jq.

Resposta

{
  "job_id": 1,
  "settings": {
    "name": "Nightly model training",
    "new_cluster": {
      "spark_version": "7.3.x-scala2.12",
      "node_type_id": "Standard_D3_v2",
      "num_workers": 10
    },
    "libraries": [
      {
        "jar": "dbfs:/my-jar.jar"
      },
      {
        "maven": {
          "coordinates": "org.jsoup:jsoup:1.7.2"
        }
      }
    ],
    "timeout_seconds": 100000000,
    "max_retries": 1,
    "schedule": {
      "quartz_cron_expression": "0 15 22 * * ?",
      "timezone_id": "America/Los_Angeles",
      "pause_status": "UNPAUSED"
    },
    "spark_jar_task": {
      "main_class_name": "com.databricks.ComputeModels"
    }
  },
  "created_time": 1457570074236
}

Estrutura de solicitação

Nome do campo Tipo Descrição
job_id INT64 O identificador canônico do trabalho sobre o qual as informações serão recuperadas. Esse campo é obrigatório.

Estrutura de resposta

Nome do campo Tipo Descrição
job_id INT64 O identificador canônico desse trabalho.
creator_user_name STRING O nome de usuário do criador. Esse campo não será incluído na resposta se o usuário tiver sido excluído.
settings JobSettings Configurações para esse trabalho e todas as suas execuções. Essas configurações podem ser atualizadas usando os pontos de extremidade Reset ou Update.
created_time INT64 A hora em que esse trabalho foi criado em milissegundos de época (milissegundos desde 1/1/1970 UTC).

Redefinir

Ponto de extremidade Método HTTP
2.0/jobs/reset POST

Substituir todas as configurações de um trabalho específico. Use o ponto de extremidade Update para atualizar as configurações de trabalho parcialmente.

Exemplo

Esta solicitação de exemplo torna o trabalho 2 idêntico ao trabalho 1 no exemplo de create.

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/reset \
--data @reset-job.json \
| jq .

reset-job.json:

{
  "job_id": 2,
  "new_settings": {
    "name": "Nightly model training",
    "new_cluster": {
      "spark_version": "7.3.x-scala2.12",
      "node_type_id": "Standard_D3_v2",
      "num_workers": 10
    },
    "libraries": [
      {
        "jar": "dbfs:/my-jar.jar"
      },
      {
        "maven": {
          "coordinates": "org.jsoup:jsoup:1.7.2"
        }
      }
    ],
    "timeout_seconds": 100000000,
    "max_retries": 1,
    "schedule": {
      "quartz_cron_expression": "0 15 22 * * ?",
      "timezone_id": "America/Los_Angeles",
      "pause_status": "UNPAUSED"
    },
    "spark_jar_task": {
      "main_class_name": "com.databricks.ComputeModels"
    }
  }
}

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • O conteúdo de reset-job.json com campos apropriados para sua solução.

Este exemplo usa um arquivo .netrc e jq.

Estrutura de solicitação

Nome do campo Tipo Descrição
job_id INT64 O identificador canônico do trabalho a ser redefinido. Esse campo é obrigatório.
new_settings JobSettings As novas configurações do trabalho. Essas configurações substituem completamente as configurações antigas.

As alterações no campo JobSettings.timeout_seconds são aplicadas a execuções ativas. As alterações em outros campos são aplicadas somente a futuras execuções.

Atualizar

Ponto de extremidade Método HTTP
2.0/jobs/update POST

Adicionar, alterar ou remover configurações específicas de um trabalho existente. Use o ponto de extremidade Reset para substituir todas as configurações do trabalho.

Exemplo

Esta solicitação de exemplo remove bibliotecas e adiciona configurações de notificação de email ao trabalho 1 definido no exemplo Create.

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/update \
--data @update-job.json \
| jq .

update-job.json:

{
  "job_id": 1,
  "new_settings": {
    "existing_cluster_id": "1201-my-cluster",
    "email_notifications": {
      "on_start": [ "someone@example.com" ],
      "on_success": [],
      "on_failure": []
    }
  },
  "fields_to_remove": ["libraries"]
}

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • O conteúdo de update-job.json com campos apropriados para sua solução.

Este exemplo usa um arquivo .netrc e jq.

Estrutura de solicitação

Nome do campo Tipo Descrição
job_id INT64 O identificador canônico do trabalho a ser atualizado. Esse campo é obrigatório.
new_settings JobSettings As novas configurações do trabalho.

Os campos de nível superior especificados em new_settings, exceto matrizes, são completamente substituídos. Matrizes são mescladas com base nos respectivos campos de chave, como task_key ou
job_cluster_key, e as entradas de matriz com a mesma chave são completamente substituídas. Com exceção da mesclagem de matriz, não há suporte para a atualização parcial de campos aninhados.

As alterações no campo JobSettings.timeout_seconds são aplicadas a execuções ativas. As alterações em outros campos são aplicadas somente a futuras execuções.
fields_to_remove Uma matriz de STRING Remover os campos de nível superior nas configurações do trabalho. Não há suporte para a remoção de campos aninhados, exceto para entradas das matrizes tasks e job_clusters. Por exemplo, veja abaixo um argumento válido para este campo:
["libraries", "schedule", "tasks/task_1", "job_clusters/Default"]

Esse campo é opcional.

Executar agora

Importante

  • Um workspace é limitado a 1.000 execuções de tarefas simultâneas. Uma resposta 429 Too Many Requests é retornada quando você solicita uma execução que não pode ser iniciada imediatamente.
  • O número de trabalhos que um workspace pode criar em uma hora é limitado a 10.000 (inclui “runs submit”). Esse limite também afeta os trabalhos criados pelos fluxos de trabalho da API REST e do notebook.
Ponto de extremidade Método HTTP
2.0/jobs/run-now POST

Execute um trabalho agora e retorne o run_id da execução disparada.

Dica

Se você invocar Create junto com Run now, poderá usar o ponto de extremidade Runs submit, o que permitirá que você envie sua carga de trabalho diretamente sem ter que criar uma tarefa.

Exemplo

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/run-now \
--data @run-job.json \
| jq .

run-job.json:

Uma solicitação de exemplo para um trabalho de notebook:

{
  "job_id": 1,
  "notebook_params": {
    "name": "john doe",
    "age": "35"
  }
}

Uma solicitação de exemplo para um trabalho de JAR:

{
  "job_id": 2,
  "jar_params": [ "john doe", "35" ]
}

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • O conteúdo de run-job.json com campos apropriados para sua solução.

Este exemplo usa um arquivo .netrc e jq.

Estrutura de solicitação

Nome do campo Tipo Descrição
job_id INT64
jar_params Uma matriz de STRING Uma lista de parâmetros para trabalhos com tarefas de JAR, por exemplo, "jar_params": ["john doe", "35"]. Os parâmetros serão usados para invocar a função principal da classe principal especificada na tarefa de JAR do Spark. Se não forem especificados em run-now, ela usará como padrão uma lista vazia. Não é possível especificar jar_params em conjunto com notebook_params. A representação JSON do campo (ou seja, {"jar_params":["john doe","35"]}) não pode exceder 10.000 bytes.
notebook_params Um mapa de ParamPair Um mapa de chaves para valores de trabalhos com tarefas de notebook, por exemplo,
"notebook_params": {"name": "john doe", "age": "35"}. O mapa é transmitido ao notebook e pode ser acessado por meio da função dbutils.widgets.get.

Se não for especificado em run-now, a execução disparada usará os parâmetros de base do trabalho.

Não é possível especificar notebook_params junto com jar_params.

A representação JSON do campo (ou seja,
{"notebook_params":{"name":"john doe","age":"35"}}) não pode exceder 10.000 bytes.
python_params Uma matriz de STRING Uma lista de parâmetros para trabalhos com tarefas do Python, por exemplo, "python_params": ["john doe", "35"]. Os parâmetros serão transmitidos ao arquivo Python como parâmetros de linha de comando. Se especificado em run-now, ele substituiria os parâmetros especificados na configuração do trabalho. A representação JSON do campo (ou seja, {"python_params":["john doe","35"]}) não pode exceder 10.000 bytes.
spark_submit_params Uma matriz de STRING Uma lista de parâmetros para trabalhos com tarefa de envio do Spark, por exemplo,
"spark_submit_params": ["--class", "org.apache.spark.examples.SparkPi"]. Os parâmetros serão transmitidos ao script spark-submit como parâmetros de linha de comando. Se especificado em run-now, ele substituiria os parâmetros especificados na configuração do trabalho. A representação JSON do campo não pode exceder 10.000 bytes.
idempotency_token STRING Um token opcional para garantir a idempotência das solicitações de execução de trabalho. Se já existir uma execução com o token fornecido, a solicitação não criará uma execução, mas retornará a ID da existente. Se uma execução com o token fornecido for excluída, um erro será retornado.

Se você especificar o token de idempotência, em caso de falha, poderá repetir a operação até que a solicitação seja bem-sucedida. O Azure Databricks garante que exatamente uma execução seja iniciada com esse token de idempotência.

O token deve ter 64 caracteres no máximo.

Para saber mais, confira Como garantir a idempotência em trabalhos.

Estrutura de resposta

Nome do campo Tipo Descrição
run_id INT64 O ID globalmente exclusivo da execução disparada recentemente.
number_in_job INT64 O número de sequência dessa execução dentre todas as execuções do trabalho.

Executa o envio

Importante

  • Um workspace é limitado a 1.000 execuções de tarefas simultâneas. Uma resposta 429 Too Many Requests é retornada quando você solicita uma execução que não pode ser iniciada imediatamente.
  • O número de trabalhos que um workspace pode criar em uma hora é limitado a 10.000 (inclui “runs submit”). Esse limite também afeta os trabalhos criados pelos fluxos de trabalho da API REST e do notebook.
Ponto de extremidade Método HTTP
2.0/jobs/runs/submit POST

Enviar uma única execução. Esse ponto de extremidade permite que você envie uma carga de trabalho diretamente sem criar uma tarefa. Use a API jobs/runs/get para verificar o estado de execução depois que o trabalho for enviado.

Exemplo

Solicitação

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/runs/submit \
--data @submit-job.json \
| jq .

submit-job.json:

{
  "run_name": "my spark task",
  "new_cluster": {
    "spark_version": "7.3.x-scala2.12",
    "node_type_id": "Standard_D3_v2",
    "num_workers": 10
  },
  "libraries": [
    {
      "jar": "dbfs:/my-jar.jar"
    },
    {
      "maven": {
        "coordinates": "org.jsoup:jsoup:1.7.2"
      }
    }
  ],
  "spark_jar_task": {
    "main_class_name": "com.databricks.ComputeModels"
  }
}

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • O conteúdo de submit-job.json com campos apropriados para sua solução.

Este exemplo usa um arquivo .netrc e jq.

Resposta

{
  "run_id": 123
}

Estrutura de solicitação

Importante

  • Quando você executa um trabalho em um novo cluster de trabalhos, ele será tratado como uma carga de trabalho Computação de Trabalhos (automatizada) sujeita aos preços da Computação de Trabalhos.
  • Quando você executa um trabalho em um cluster de uso geral existente, ele é tratado como uma carga de trabalho Computação para Todas as Finalidades (interativa) sujeita aos preços da Computação para Todas as Finalidades.
Nome do campo Tipo Descrição
existing_cluster_id OU new_cluster STRING OU NewCluster Se for existing_cluster_id, será o ID de um cluster existente que será usado para todas as execuções desse trabalho. Ao executar trabalhos em um cluster existente, talvez seja necessário reiniciar manualmente o cluster caso ele pare de responder. Sugerimos a execução de trabalhos em novos clusters para maior confiabilidade.

Se for new_cluster, será uma descrição de um cluster que será criado para cada execução.

Se você estiver especificando uma PipelineTask, esse campo poderá ficar vazio.
notebook_task OU spark_jar_task OU
spark_python_task OU spark_submit_task OU
pipeline_task OU run_job_task		 NotebookTask OU SparkJarTask OU SparkPythonTask OU SparkSubmitTask OU PipelineTask OU RunJobTask Se for notebook_task, isso indicará que esse trabalho deve executar um notebook. Esse campo não pode ser especificado em conjunto com spark_jar_task.

Se for spark_jar_task, isso indicará que esse trabalho deve executar um JAR.

Se for spark_python_task, isso indicará que esse trabalho deve executar um arquivo Python.

Se for spark_submit_task, isso indicará que esse trabalho deve ser lançado pelo script de envio do Spark.

Se for pipeline_task, isso indicará que esse trabalho deve executar um pipeline do Delta Live Tables.

Se for run_job_task, isso indica que esse trabalho deve executar outro trabalho.
run_name STRING Um nome opcional para a execução. O valor padrão é Untitled.
webhook_notifications WebhookNotifications Um conjunto opcional de destinos do sistema para notificar quando as execuções deste trabalho começam, são concluídas ou falham.
notification_settings JobNotificationSettings Configurações de notificação opcionais que são usadas ao enviar notificações para cada um dos webhook_notifications para esse trabalho.
libraries Uma matriz de Biblioteca Uma lista opcional de bibliotecas a serem instaladas no cluster que executará o trabalho. O valor padrão é uma lista vazia.
timeout_seconds INT32 Um tempo limite opcional aplicado a cada execução desse trabalho. O comportamento padrão é sem tempo limite.
idempotency_token STRING Um token opcional para garantir a idempotência das solicitações de execução de trabalho. Se já existir uma execução com o token fornecido, a solicitação não criará uma execução, mas retornará a ID da existente. Se uma execução com o token fornecido for excluída, um erro será retornado.

Se você especificar o token de idempotência, em caso de falha, poderá repetir a operação até que a solicitação seja bem-sucedida. O Azure Databricks garante que exatamente uma execução seja iniciada com esse token de idempotência.

O token deve ter 64 caracteres no máximo.

Para saber mais, confira Como garantir a idempotência em trabalhos.

Estrutura de resposta

Nome do campo Tipo Descrição
run_id INT64 O identificador canônico para a execução recém-enviada.

Executa a lista

Ponto de extremidade Método HTTP
2.0/jobs/runs/list GET

A lista é executada em ordem decrescente por hora de início.

Observação

As execuções são removidas automaticamente após 60 dias. Se você quiser fazer referência a elas após 60 dias, deverá salvar os resultados de execução antigos antes que eles expirem. Para exportar usando a interface do usuário, confira Exportar resultados da execução do trabalho. Para exportar usando a API de Trabalhos, confira Exportação de execuções.

Exemplo

Solicitação

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/jobs/runs/list?job_id=<job-id>&active_only=<true-false>&offset=<offset>&limit=<limit>&run_type=<run-type>' \
| jq .

Ou:

curl --netrc --get \
https://<databricks-instance>/api/2.0/jobs/runs/list \
--data 'job_id=<job-id>&active_only=<true-false>&offset=<offset>&limit=<limit>&run_type=<run-type>' \
| jq .

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • <job-id> com o ID do trabalho, por exemplo, 123.
  • <true-false> com true ou false.
  • <offset>com o valor offset.
  • <limit>com o valor limit.
  • <run-type>com o valor run_type.

Este exemplo usa um arquivo .netrc e jq.

Resposta

{
  "runs": [
    {
      "job_id": 1,
      "run_id": 452,
      "number_in_job": 5,
      "state": {
        "life_cycle_state": "RUNNING",
        "state_message": "Performing action"
      },
      "task": {
        "notebook_task": {
          "notebook_path": "/Users/donald@duck.com/my-notebook"
        }
      },
      "cluster_spec": {
        "existing_cluster_id": "1201-my-cluster"
      },
      "cluster_instance": {
        "cluster_id": "1201-my-cluster",
        "spark_context_id": "1102398-spark-context-id"
      },
      "overriding_parameters": {
        "jar_params": ["param1", "param2"]
      },
      "start_time": 1457570074236,
      "end_time": 1457570075149,
      "setup_duration": 259754,
      "execution_duration": 3589020,
      "cleanup_duration": 31038,
      "run_duration": 3879812,
      "trigger": "PERIODIC"
    }
  ],
  "has_more": true
}

Estrutura de solicitação

Nome do campo Tipo Descrição
active_only OU completed_only BOOL OU BOOL Se active_only for true, somente as execuções ativas serão incluídas nos resultados; caso contrário, ele listará as execuções ativas e concluídas. Uma execução ativa é uma execução em RunLifecycleStatePENDING, RUNNINGou TERMINATING. Esse campo não pode ser true quando completed_only é true.

Se completed_only for true, somente as execuções concluídas serão incluídas nos resultados; caso contrário, ele listará as execuções ativas e concluídas. Esse campo não pode ser true quando active_only é true.
job_id INT64 O trabalho para o qual as execuções são listadas. Se omitido, o serviço Trabalhos listará execuções de todos os trabalhos.
offset INT32 O deslocamento da primeira execução a ser retornada em relação à última.
limit INT32 O número de execuções a ser retornado. Esse valor deve ser maior que 0 e menor que 1000. O valor padrão é 20. Se uma solicitação especificar um limite de 0, o serviço usará o limite máximo.
run_type STRING O tipo de execuções a ser retornado. Para ver uma descrição dos tipos de execução, confira Run.

Estrutura de resposta

Nome do campo Tipo Descrição
runs Uma matriz de Run Uma lista de execuções, da iniciada mais recentemente à menos recente.
has_more BOOL Se true, as execuções adicionais correspondentes ao filtro fornecido ficarão disponíveis para listagem.

Executa Get

Ponto de extremidade Método HTTP
2.0/jobs/runs/get GET

Recuperar os metadados de uma execução.

Observação

As execuções são removidas automaticamente após 60 dias. Se você quiser fazer referência a elas após 60 dias, deverá salvar os resultados de execução antigos antes que eles expirem. Para exportar usando a interface do usuário, confira Exportar resultados da execução do trabalho. Para exportar usando a API de Trabalhos, confira Exportação de execuções.

Exemplo

Solicitação

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/jobs/runs/get?run_id=<run-id>' \
| jq .

Ou:

curl --netrc --get \
https://<databricks-instance>/api/2.0/jobs/runs/get \
--data run_id=<run-id> \
| jq .

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • <run-id> com o ID da execução, por exemplo, 123.

Este exemplo usa um arquivo .netrc e jq.

Resposta

{
  "job_id": 1,
  "run_id": 452,
  "number_in_job": 5,
  "state": {
    "life_cycle_state": "RUNNING",
    "state_message": "Performing action"
  },
  "task": {
    "notebook_task": {
      "notebook_path": "/Users/someone@example.com/my-notebook"
    }
  },
  "cluster_spec": {
    "existing_cluster_id": "1201-my-cluster"
  },
  "cluster_instance": {
    "cluster_id": "1201-my-cluster",
    "spark_context_id": "1102398-spark-context-id"
  },
  "overriding_parameters": {
    "jar_params": ["param1", "param2"]
  },
  "start_time": 1457570074236,
  "end_time": 1457570075149,
  "setup_duration": 259754,
  "execution_duration": 3589020,
  "cleanup_duration": 31038,
  "run_duration": 3879812,
  "trigger": "PERIODIC"
}

Estrutura de solicitação

Nome do campo Tipo Descrição
run_id INT64 O identificador canônico da execução para a qual os metadados devem ser recuperados. Esse campo é obrigatório.

Estrutura de resposta

Nome do campo Tipo Descrição
job_id INT64 O identificador canônico do trabalho que contém essa execução.
run_id INT64 O identificador canônico da execução. Esse ID é exclusivo em todas as execuções de todos os trabalhos.
number_in_job INT64 O número de sequência dessa execução dentre todas as execuções do trabalho. Esse valor começa em 1.
original_attempt_run_id INT64 Se essa é uma nova tentativa de uma tentativa de execução anterior, esse campo contém o run_id da tentativa original; caso contrário, é o mesmo run_id.
state RunState O resultado e os estados de ciclo de vida da execução.
schedule CronSchedule A agenda Cron que disparou essa operação se ela foi disparada pelo agendador periódico.
task JobTask A tarefa executada pela execução, se houver.
cluster_spec ClusterSpec Um instantâneo da especificação de cluster do trabalho quando a execução foi criada.
cluster_instance ClusterInstance O cluster usado para essa execução. Se houver especificação para a execução usar um novo cluster, esse campo será definido depois que o serviço Trabalhos tiver solicitado um cluster para a execução.
overriding_parameters RunParameters Os parâmetros usados para essa execução.
start_time INT64 A hora em que essa execução foi iniciada em milissegundos de época (milissegundos desde 1/1/1970 UTC). Essa pode não ser a hora em que a tarefa de trabalho começa a ser executada, por exemplo, se o trabalho estiver agendado para execução em um novo cluster, essa será a hora em que a chamada de criação do cluster foi feita.
end_time INT64 A hora em que essa execução terminou em milissegundos de época (milissegundos desde 1/1/1970 UTC). Esse campo será definido como 0 se o trabalho ainda estiver em execução.
setup_duration INT64 O tempo em milissegundos necessário para configurar o cluster. Para as execuções feitas em novos clusters, esse é o tempo de criação do cluster; para as execuções feitas em clusters existentes, o tempo deve ser muito curto. A duração total da execução é a soma de setup_duration,
execution_duration e o cleanup_duration. O campo setup_duration é definido como 0 para execuções de trabalho de várias tarefas. A duração total de uma execução de trabalho de várias tarefas é o valor do
campo run_duration.
execution_duration INT64 O tempo em milissegundos que levou para executar os comandos no JAR ou notebook até eles serem concluídos, falharem, atingirem o tempo limite, serem cancelados ou encontrarem um erro inesperado. A duração total da execução é a soma de setup_duration, execution_duration e o
cleanup_duration. O campo execution_duration é definido como 0 para execuções de trabalho de várias tarefas. A duração total de uma execução de trabalho de várias tarefas é o valor do campo run_duration.
cleanup_duration INT64 O tempo em milissegundos necessário para terminar o cluster e limpar todos os artefatos associados. A duração total da execução é a soma de setup_duration, execution_duration e o cleanup_duration. O campo cleanup_duration é definido como 0 para execuções de trabalho de várias tarefas. A duração total de uma execução de trabalho de várias tarefas é o valor do campo run_duration.
run_duration INT64 O tempo em milissegundos necessário para finalizar a execução do trabalho e todos os seus reparos. Esse campo só é definido para execuções de trabalho de várias tarefas e não para execuções de tarefas. A duração de uma execução de tarefa é a soma de
setup_duration, execution_duration e o cleanup_duration.
trigger TriggerType O tipo de gatilho que disparou essa execução.
creator_user_name STRING O nome de usuário do criador. Esse campo não será incluído na resposta se o usuário tiver sido excluído
run_page_url STRING A URL para a página de detalhes da execução.

Executa a exportação

Ponto de extremidade Método HTTP
2.0/jobs/runs/export GET

Exportar e recuperar a tarefa de execução do trabalho.

Observação

Somente execuções de notebook podem ser exportadas em formato HTML. A exportação de execuções de outros tipos falhará.

Exemplo

Solicitação

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/jobs/runs/export?run_id=<run-id>' \
| jq .

Ou:

curl --netrc --get \
https://<databricks-instance>/api/2.0/jobs/runs/export \
--data run_id=<run-id> \
| jq .

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • <run-id> com o ID da execução, por exemplo, 123.

Este exemplo usa um arquivo .netrc e jq.

Resposta

{
  "views": [ {
    "content": "<!DOCTYPE html><html><head>Head</head><body>Body</body></html>",
    "name": "my-notebook",
    "type": "NOTEBOOK"
  } ]
}

Para extrair o notebook HTML da resposta JSON, baixe e execute este script Python.

Observação

O corpo do notebook no objeto __DATABRICKS_NOTEBOOK_MODEL está codificado.

Estrutura de solicitação

Nome do campo Tipo Descrição
run_id INT64 O identificador canônico da execução. Esse campo é obrigatório.
views_to_export ViewsToExport Quais exibições exportar (CODE, DASHBOARDS ou ALL). Usa como padrão CODE.

Estrutura de resposta

Nome do campo Tipo Descrição
views Uma matriz de ViewItem O conteúdo exportado no formato HTML (um para cada item de exibição).

Executa o cancelamento

Ponto de extremidade Método HTTP
2.0/jobs/runs/cancel POST

Cancelar uma execução de trabalho. Já que a execução é cancelada de maneira assíncrona, ela poderá ainda estar em execução quando esta solicitação for concluída. A execução será terminada em breve. Se a execução já estiver em um terminal life_cycle_state, esse método será não operacional.

Esse ponto de extremidade valida que o parâmetro run_id é válido e, para parâmetros inválidos, retorna o código de status HTTP 400.

Exemplo

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/runs/cancel \
--data '{ "run_id": <run-id> }'

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • <run-id> com o ID da execução, por exemplo, 123.

Este exemplo usa um arquivo .netrc.

Estrutura de solicitação

Nome do campo Tipo Descrição
run_id INT64 O identificador canônico da execução a ser cancelada. Esse campo é obrigatório.

Executa cancelar tudo

Ponto de extremidade Método HTTP
2.0/jobs/runs/cancel-all POST

Cancelar todas as execuções ativas de um trabalho. Como a execução é cancelada de maneira assíncrona, ela não impede que novas execuções sejam iniciadas.

Esse ponto de extremidade valida que o parâmetro job_id é válido e, para parâmetros inválidos, retorna o código de status HTTP 400.

Exemplo

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/runs/cancel-all \
--data '{ "job_id": <job-id> }'

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • <job-id> com o ID do trabalho, por exemplo, 123.

Este exemplo usa um arquivo .netrc.

Estrutura de solicitação

Nome do campo Tipo Descrição
job_id INT64 O identificador canônico do trabalho cujas todas as execuções cancelar. Esse campo é obrigatório.

Executa a saída Get

Ponto de extremidade Método HTTP
2.0/jobs/runs/get-output GET

Recupere a saída e os metadados de uma única execução de tarefa. Quando uma tarefa de notebook retorna um valor por meio da chamada dbutils.notebook.exit (), você pode usar esse ponto de extremidade para recuperar aquele valor. O Azure Databricks restringe essa API para retornar os primeiros 5 MB da saída. Para retornar um resultado maior, você pode armazenar os resultados do trabalho em um serviço de armazenamento em nuvem.

Esse ponto de extremidade valida que o parâmetro run_id é válido e, para parâmetros inválidos, retorna o código de status HTTP 400.

As execuções são removidas automaticamente após 60 dias. Se você quiser fazer referência a elas após 60 dias, deverá salvar os resultados de execução antigos antes que eles expirem. Para exportar usando a interface do usuário, confira Exportar resultados da execução do trabalho. Para exportar usando a API de Trabalhos, confira Exportação de execuções.

Exemplo

Solicitação

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/jobs/runs/get-output?run_id=<run-id>' \
| jq .

Ou:

curl --netrc --get \
https://<databricks-instance>/api/2.0/jobs/runs/get-output \
--data run_id=<run-id> \
| jq .

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • <run-id> com o ID da execução, por exemplo, 123.

Este exemplo usa um arquivo .netrc e jq.

Resposta

{
  "metadata": {
    "job_id": 1,
    "run_id": 452,
    "number_in_job": 5,
    "state": {
      "life_cycle_state": "TERMINATED",
      "result_state": "SUCCESS",
      "state_message": ""
    },
    "task": {
      "notebook_task": {
        "notebook_path": "/Users/someone@example.com/my-notebook"
      }
    },
    "cluster_spec": {
      "existing_cluster_id": "1201-my-cluster"
    },
    "cluster_instance": {
      "cluster_id": "1201-my-cluster",
      "spark_context_id": "1102398-spark-context-id"
    },
    "overriding_parameters": {
      "jar_params": ["param1", "param2"]
    },
    "start_time": 1457570074236,
    "setup_duration": 259754,
    "execution_duration": 3589020,
    "cleanup_duration": 31038,
    "run_duration": 3879812,
    "trigger": "PERIODIC"
  },
  "notebook_output": {
    "result": "the maybe truncated string passed to dbutils.notebook.exit()"
  }
}

Estrutura de solicitação

Nome do campo Tipo Descrição
run_id INT64 O identificador canônico da execução. Para um trabalho com várias tarefas, esse é o run_id da execução de uma tarefa. Consulte Obtenção da saída de execuções. Esse campo é obrigatório.

Estrutura de resposta

Nome do campo Tipo Descrição
notebook_output OU error NotebookOutput OU STRING Se for notebook_output, será a saída de uma tarefa de notebook, se disponível. Uma tarefa de notebook que termina (com êxito ou com falha) sem chamar
dbutils.notebook.exit() é considerada como resultando em uma saída vazia. Esse campo será definido, mas seu valor de resultado estará vazio.

Se houver erro, haverá uma mensagem de erro indicando por que a saída não está disponível. A mensagem não é estruturada, e o formato exato está sujeito a alterações.
metadata Executar Todos os detalhes da execução, exceto da sua saída.

Executa a exclusão

Ponto de extremidade Método HTTP
2.0/jobs/runs/delete POST

Excluir uma execução não ativa. Retornará um erro se a execução estiver ativa.

Exemplo

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/jobs/runs/delete \
--data '{ "run_id": <run-id> }'

Substitua:

  • <databricks-instance> pelo nome da instância do workspace do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • <run-id> com o ID da execução, por exemplo, 123.

Este exemplo usa um arquivo .netrc.

Estrutura de solicitação

Nome do campo Tipo Descrição
run_id INT64 O identificador canônico da execução para a qual os metadados devem ser recuperados.

Estruturas de dados

Nesta seção:

ABFSSStorageInfo

Informações de armazenamento do ADLS (Azure Data Lake Storage).

Nome do campo Tipo Descrição
destination STRING Destino do arquivo. Exemplo: abfss://...

AutoScale

Intervalo que define o número mínimo e máximo de trabalhos do cluster.

Nome do campo Tipo Descrição
min_workers INT32 O número mínimo de trabalhos até o qual o cluster pode ser reduzido verticalmente quando subutilizado. Também é o número inicial de trabalhos que o cluster terá após a criação.
max_workers INT32 O número máximo de trabalhos até o qual o cluster pode ser escalado verticalmente quando sobrecarregado. max_workers precisa ser estritamente maior que min_workers.

AzureAttributes

Atributos definidos durante a criação do cluster relacionados ao Azure.

Nome do campo Tipo Descrição
first_on_demand INT32 Os primeiros nós first_on_demand do cluster serão colocados em instâncias sob demanda. Esse valor precisa ser maior que 0 ou a validação de criação do cluster falhará. Se esse valor for maior ou igual ao tamanho do cluster atual, todos os nós serão colocados em instâncias sob demanda. Se esse valor for menor que o tamanho do cluster atual, os nós first_on_demand serão colocados em instâncias sob demanda e o restante será colocado em instâncias de disponibilidade. Esse valor não afeta o tamanho do cluster e não pode ser transformado durante o tempo de vida de um cluster.
availability AzureAvailability Tipo de disponibilidade usado para todos os nós posteriores após aqueles first_on_demand.
spot_bid_max_price DOUBLE O preço máximo de oferta usado para instâncias spot do Azure. É possível definir isso como maior ou igual ao preço do spot atual. Também pode definir isso como -1 (o padrão), o que especifica que a instância não pode ser removida com base no preço. O preço da instância será o preço atual das instâncias spot ou o preço de uma instância padrão. Veja os preços históricos e as taxas de remoção no portal do Azure.

AzureAvailability

O comportamento do tipo de disponibilidade da instância do Azure.

Type Descrição
SPOT_AZURE Use instâncias spot.
ON_DEMAND_AZURE Use instâncias sob demanda.
SPOT_WITH_FALLBACK_AZURE Preferencialmente, use instâncias spot, mas volte para instâncias sob demanda se as instâncias spot não puderem ser adquiridas (por exemplo, se os preços do spot do Azure forem muito altos ou estiverem fora da cota). Não se aplica à disponibilidade do pool.

ClusterInstance

Identificadores para o cluster e o contexto do Spark usados por uma execução. Esses dois valores, juntos, identificam um contexto de execução durante todo o tempo.

Nome do campo Tipo Descrição
cluster_id STRING O identificador canônico do cluster usado por uma execução. Esse campo está sempre disponível para execuções em clusters existentes. Para execuções em novos clusters, ele fica disponível quando o cluster é criado. Esse valor pode ser usado para exibir logs pelo acesso a /#setting/sparkui/$cluster_id/driver-logs. Os logs continuarão disponíveis após a conclusão da execução.

A resposta não incluirá esse campo se o identificador ainda não estiver disponível.
spark_context_id STRING O identificador canônico para o contexto do Spark usado por uma execução. Esse campo será preenchido quando a execução começar a ser executada. Esse valor pode ser usado para exibir a interface do usuário do Spark pelo acesso a /#setting/sparkui/$cluster_id/$spark_context_id. A interface do usuário do Spark continuará disponível após a conclusão da execução.

A resposta não incluirá esse campo se o identificador ainda não estiver disponível.

ClusterLogConf

Caminho para o log do cluster.

Nome do campo Tipo Descrição
dbfs DbfsStorageInfo Local do DBFS do log do cluster. O destino precisa ser fornecido. Por exemplo,
{ "dbfs" : { "destination" : "dbfs:/home/cluster_log" } }

ClusterSpec

Importante

  • Quando você executa um trabalho em um novo cluster de trabalhos, ele será tratado como uma carga de trabalho Computação de Trabalhos (automatizada) sujeita aos preços da Computação de Trabalhos.
  • Quando você executa um trabalho em um cluster de uso geral existente, ele é tratado como uma carga de trabalho Computação para Todas as Finalidades (interativa) sujeita aos preços da Computação para Todas as Finalidades.
Nome do campo Tipo Descrição
existing_cluster_id OU new_cluster STRING OU NewCluster Se for existing_cluster_id, será o ID de um cluster existente que será usado para todas as execuções desse trabalho. Ao executar trabalhos em um cluster existente, talvez seja necessário reiniciar manualmente o cluster caso ele pare de responder. Sugerimos a execução de trabalhos em novos clusters para maior confiabilidade.

Se for new_cluster, será uma descrição de um cluster que será criado para cada execução.

Se você estiver especificando uma PipelineTask, esse campo poderá ficar vazio.
libraries Uma matriz de Biblioteca Uma lista opcional de bibliotecas a serem instaladas no cluster que executará o trabalho. O valor padrão é uma lista vazia.

ClusterTag

Definição de marca do cluster.

Type Descrição
STRING A chave da marca. A chave:

* Precisa ter entre 1 e 512 caracteres
* Não deve conter nenhum dos caracteres <>%*&+?\\/
* Não deve começar com azure, microsoft ou windows
STRING O valor da marca. O tamanho do valor precisa ser menor ou igual a 256 caracteres UTF-8.

CronSchedule

Nome do campo Tipo Descrição
quartz_cron_expression STRING Uma expressão Cron que usa a sintaxe Quartz que descreve o agendamento de um trabalho. Confira o Gatilho Cron para obter detalhes. Esse campo é obrigatório.
timezone_id STRING Um ID de fuso horário Java. O agendamento de um trabalho será resolvido em relação a esse fuso horário. Confira Fuso horário Java para obter detalhes. Esse campo é obrigatório.
pause_status STRING Indicar se esse agendamento está em pausa ou não. “EM PAUSA” ou “SEM PAUSA”.

DbfsStorageInfo

Informações de armazenamento do DBFS.

Nome do campo Tipo Descrição
destination STRING Destino do DBFS. Exemplo: dbfs:/my/path

FileStorageInfo

Informações de armazenamento de arquivos.

Observação

Esse tipo de local só está disponível para clusters configurados por meio dos Serviços de Contêiner do Databricks.

Nome do campo Tipo Descrição
destination STRING Destino do arquivo. Exemplo: file:/my/file.sh

InitScriptInfo

Caminho para um script de inicialização.

Para obter instruções sobre como usar scripts de inicialização com os Serviços de Contêiner do Databricks, confira Usar um script de inicialização.

Observação

O tipo de armazenamento de arquivos (nome do campo: file) só está disponível para clusters configurados por meio dos Serviços de Contêiner do Databricks. Confira FileStorageInfo.

Nome do campo Tipo Descrição
workspace OU
dbfs (preterido)

OR
abfss		 WorkspaceStorageInfo

DbfsStorageInfo (preterido)

ABFSSStorageInfo		 Local do workspace do script de inicialização. O destino precisa ser fornecido. Por exemplo,
{ "workspace" : { "destination" : "/Users/someone@domain.com/init_script.sh" } }

(Preterido) Local DBFS do script de inicialização. O destino precisa ser fornecido. Por exemplo,
{ "dbfs" : { "destination" : "dbfs:/home/init_script" } }

Local do ADLS (Azure Data Lake Storage do script de inicialização. O destino precisa ser fornecido. Por exemplo, { "abfss": { "destination" : "abfss://..." } }

Job

Nome do campo Tipo Descrição
job_id INT64 O identificador canônico desse trabalho.
creator_user_name STRING O nome de usuário do criador. Esse campo não será incluído na resposta se o usuário já tiver sido excluído.
run_as STRING O nome de usuário para o qual o trabalho será executado. run_as é baseado nas configurações de trabalho atuais e é definido como o criador do trabalho quando o controle de acesso ao trabalho está desabilitado, ou a permissão is_owner quando o controle de acesso ao trabalho está habilitado.
settings JobSettings Configurações para esse trabalho e todas as suas execuções. Essas configurações podem ser atualizadas com o método resetJob.
created_time INT64 A hora em que esse trabalho foi criado em milissegundos de época (milissegundos desde 1/1/1970 UTC).

JobEmailNotifications

Importante

Os campos on_start, on_success e on_failure aceitam apenas caracteres latinos (conjunto de caracteres ASCII). O uso de caracteres não ASCII retornará um erro. Entre os exemplos de caracteres não ASCII inválidos estão o chinês, os kanjis do japonês e os emojis.

Nome do campo Tipo Descrição
on_start Uma matriz de STRING Uma lista de endereços de email a serem notificados quando uma execução for iniciada. Se não for especificada na criação, redefinição ou atualização do trabalho, a lista estará vazia e as notificações não serão enviadas.
on_success Uma matriz de STRING Uma lista de endereços de email a serem notificados quando uma execução for concluída com êxito. Uma execução será considerada concluída com êxito se terminar com TERMINATEDlife_cycle_state e um SUCCESSFULresult_state. Se não for especificada na criação, redefinição ou atualização do trabalho, a lista estará vazia e as notificações não serão enviadas.
on_failure Uma matriz de STRING Uma lista de endereços de email a serem notificados quando uma execução for concluída sem êxito. Uma execução é considerada concluída sem êxito quando termina com INTERNAL_ERROR
life_cycle_state ou SKIPPED, FAILED, ou result_state TIMED_OUT. Se não for especificada na criação, redefinição ou atualização do trabalho, a lista estará vazia e as notificações não serão enviadas.
on_duration_warning_threshold_exceeded Uma matriz de STRING Uma lista de endereços de email a serem notificados quando a duração de uma execução exceder o limite especificado para a métrica RUN_DURATION_SECONDS no campo health. Se nenhuma regra para a métrica RUN_DURATION_SECONDS for especificada no campo health do trabalho, as notificações não serão enviadas.
no_alert_for_skipped_runs BOOL Se true, não envia email para destinatários especificados em on_failure quando a execução é ignorada.
Nome do campo Tipo Descrição
on_start Uma matriz de Webhook Uma lista de destinos do sistema a serem notificados quando uma execução for iniciada. Se não for especificada na criação, redefinição ou atualização do trabalho, a lista estará vazia e as notificações não serão enviadas. No máximo três destinos podem ser especificados para a propriedade on_start.
on_success Uma matriz de Webhook Uma lista de destinos do sistema a serem notificados quando uma execução for concluída com êxito. Uma execução será considerada concluída com êxito se terminar com TERMINATEDlife_cycle_state e um SUCCESSFULresult_state. Se não for especificada na criação, redefinição ou atualização do trabalho, a lista estará vazia e as notificações não serão enviadas. No máximo três destinos podem ser especificados para a propriedade on_success.
on_failure Uma matriz de Webhook Uma lista de destinos do sistema a serem notificados quando uma execução for concluída sem êxito. Uma execução é considerada concluída sem êxito quando termina com INTERNAL_ERROR
life_cycle_state ou SKIPPED, FAILED, ou result_state TIMED_OUT. Se não for especificada na criação, redefinição ou atualização do trabalho, a lista estará vazia e as notificações não serão enviadas. No máximo três destinos podem ser especificados para a propriedade on_failure.
on_duration_warning_threshold_exceeded Uma matriz de Webhook Uma lista opcional de endereços de email a serem notificados quando a duração de uma execução exceder o limite especificado para a métrica RUN_DURATION_SECONDS no campo health. No máximo três destinos podem ser especificados para a propriedade on_duration_warning_threshold_exceeded.

JobNotificationSettings

Nome do campo Tipo Descrição
no_alert_for_skipped_runs BOOL Se true, não envia email para destinatários especificados em on_failure quando a execução é ignorada.
no_alert_for_canceled_runs BOOL Se for true, não envie notificações aos destinatários especificados em on_failure se a execução for cancelada.
alert_on_last_attempt BOOL Se for true, não envie notificações aos destinatários especificados em on_start para as execuções repetidas e não envie notificações aos destinatários especificados em on_failure até a última repetição da execução.

JobSettings

Importante

  • Quando você executa um trabalho em um novo cluster de trabalhos, ele será tratado como uma carga de trabalho Computação de Trabalhos (automatizada) sujeita aos preços da Computação de Trabalhos.
  • Quando você executa um trabalho em um cluster de uso geral existente, ele é tratado como uma carga de trabalho Computação para Todas as Finalidades (interativa) sujeita aos preços da Computação para Todas as Finalidades.

Configurações para um trabalho. Essas configurações podem ser atualizadas com o método resetJob.

Nome do campo Tipo Descrição
existing_cluster_id OU new_cluster STRING OU NewCluster Se for existing_cluster_id, será o ID de um cluster existente que será usado para todas as execuções desse trabalho. Ao executar trabalhos em um cluster existente, talvez seja necessário reiniciar manualmente o cluster caso ele pare de responder. Sugerimos a execução de trabalhos em novos clusters para maior confiabilidade.

Se for new_cluster, será uma descrição de um cluster que será criado para cada execução.

Se você estiver especificando uma PipelineTask, esse campo poderá ficar vazio.
notebook_task OU spark_jar_task OU
spark_python_task OU spark_submit_task OU
pipeline_task OU run_job_task		 NotebookTask OU SparkJarTask OU SparkPythonTask OU SparkSubmitTask OU PipelineTask OU RunJobTask Se for notebook_task, isso indicará que esse trabalho deve executar um notebook. Esse campo não pode ser especificado em conjunto com spark_jar_task.

Se for spark_jar_task, isso indicará que esse trabalho deve executar um JAR.

Se for spark_python_task, isso indicará que esse trabalho deve executar um arquivo Python.

Se for spark_submit_task, isso indicará que esse trabalho deve ser lançado pelo script de envio do Spark.

Se for pipeline_task, isso indicará que esse trabalho deve executar um pipeline do Delta Live Tables.

Se for run_job_task, isso indica que esse trabalho deve executar outro trabalho.
name STRING Um nome opcional para o trabalho. O valor padrão é Untitled.
libraries Uma matriz de Biblioteca Uma lista opcional de bibliotecas a serem instaladas no cluster que executará o trabalho. O valor padrão é uma lista vazia.
email_notifications JobEmailNotifications Um conjunto opcional de endereços de email que serão notificados quando as execuções desse trabalho forem iniciadas ou concluídas e quando esse trabalho for excluído. O comportamento padrão é não enviar emails.
webhook_notifications WebhookNotifications Um conjunto opcional de destinos do sistema para notificar quando as execuções deste trabalho começam, são concluídas ou falham.
notification_settings JobNotificationSettings Configurações de notificação opcionais que são usadas ao enviar notificações para cada um dos email_notifications e webhook_notifications para esse trabalho.
timeout_seconds INT32 Um tempo limite opcional aplicado a cada execução desse trabalho. O comportamento padrão é sem tempo limite.
max_retries INT32 Um número máximo opcional de repetições de uma tentativa malsucedida. Uma execução será considerada malsucedida se for concluída com o result_state FAILED ou
INTERNAL_ERROR
life_cycle_state. O valor -1 significa novas tentativas indefinidamente; o valor 0 significa nunca tentar novamente. O comportamento padrão é nunca tentar novamente.
min_retry_interval_millis INT32 Um intervalo mínimo opcional em milissegundos entre tentativas. O comportamento padrão é que as execuções malsucedidas sejam imediatamente tentadas novamente.
retry_on_timeout BOOL Uma política opcional para especificar se deve haver nova tentativa de um trabalho quando ele atinge o tempo limite. O comportamento padrão é não tentar novamente no tempo limite.
schedule CronSchedule Um agendamento periódico opcional para esse trabalho. O comportamento padrão é o trabalho ser executado somente quando disparado pelo clique em “Executar Agora” na interface do usuário Trabalhos ou pelo envio de uma solicitação de API a
runNow.
max_concurrent_runs INT32 Um número máximo permitido opcional de execuções simultâneas do trabalho.

Defina esse valor se você quiser ser capaz de fazer várias execuções do mesmo trabalho simultaneamente. Isso é útil, por exemplo, se você dispara seu trabalho em um agendamento frequente e quer permitir que as execuções consecutivas se sobreponham ou se quer disparar várias execuções que tenham diferença nos parâmetros de entrada.

Essa configuração afeta somente novas execuções. Por exemplo, digamos que a simultaneidade do trabalho seja quatro e existem quatro execuções ativas simultâneas. A definição da simultaneidade como 3 não desativará nenhuma das execuções ativas. No entanto, a partir daí, novas execuções serão ignoradas, a menos que haja menos de três execuções ativas.

O valor não pode exceder 1000. A definição desse valor como 0 faz com que todas as novas execuções sejam ignoradas. O comportamento padrão é permitir apenas uma execução simultânea.
health JobsHealthRules Um conjunto opcional de regras de integridade definidas para o trabalho.

JobTask

Nome do campo Tipo Descrição
notebook_task OU spark_jar_task OU
spark_python_task OU spark_submit_task OU
pipeline_task OU run_job_task		 NotebookTask OU SparkJarTask OU SparkPythonTask OU SparkSubmitTask OU PipelineTask OU RunJobTask Se for notebook_task, isso indicará que esse trabalho deve executar um notebook. Esse campo não pode ser especificado em conjunto com spark_jar_task.

Se for spark_jar_task, isso indicará que esse trabalho deve executar um JAR.

Se for spark_python_task, isso indicará que esse trabalho deve executar um arquivo Python.

Se for spark_submit_task, isso indicará que esse trabalho deve ser lançado pelo script de envio do Spark.

Se for pipeline_task, isso indicará que esse trabalho deve executar um pipeline do Delta Live Tables.

Se for run_job_task, isso indica que esse trabalho deve executar outro trabalho.

JobsHealthRule

Nome do campo Tipo Descrição
metric STRING Especifica a métrica de integridade que está sendo avaliada para uma regra de integridade específica. Os valores válidos são RUN_DURATION_SECONDS.
operator STRING Especifica o operador usado para comparar o valor da métrica de integridade com o limite especificado. Os valores válidos são GREATER_THAN.
value INT32 Especifica o valor limite que a métrica de integridade deve atender para cumprir a regra de integridade.

JobsHealthRules

Nome do campo Tipo Descrição
rules Uma matriz de JobsHealthRule Um conjunto opcional de regras de integridade que pode ser definido para um trabalho.

Biblioteca

Nome do campo Tipo Descrição
jar OU egg OU whl OU
pypi OU maven OU cran		 STRING ou STRING ou STRING ou PythonPyPiLibrary ou MavenLibrary ou RCranLibrary Se jar, o URI do JAR a ser instalado. Há suporte para URIs do DBFS e ADLS ( abfss ). Por exemplo: { "jar": "dbfs:/mnt/databricks/library.jar" } ou
{ "jar": "abfss://<container-path>/library.jar" }. Se o ADLS for usado, verifique se o cluster tem acesso de leitura na biblioteca.

Se o gema, o URI do gema a ser instalado. Há suporte para URIs do DBFS e ADLS. Por exemplo: { "egg": "dbfs:/my/egg" } ou
{ "egg": "abfss://<container-path>/egg" }.

Se whl, URI do wheel ou wheels compactado a ser instalado. Há suporte para URIs do DBFS e ADLS. Por exemplo: { "whl": "dbfs:/my/whl" } ou
{ "whl": "abfss://<container-path>/whl" }. Se o ADLS for usado, verifique se o cluster tem acesso de leitura na biblioteca. Além disso, o nome do arquivo wheel precisa utilizar a convenção correta. Se for necessário instalar o arquivo zipado wheels, o sufixo do nome do arquivo deverá ser .wheelhouse.zip.

Se o PyPI, a especificação de uma biblioteca de PyPI a ser instalada. A especificação do campo repo é opcional e, se não for especificado, o índice Pip padrão será usado. Por exemplo:
{ "package": "simplejson", "repo": "https://my-repo.com" }

Se Maven, a especificação de uma biblioteca de Maven a ser instalada. Por exemplo:
{ "coordinates": "org.jsoup:jsoup:1.7.2" }

Se o Cran, a especificação de uma biblioteca de CRAN a ser instalada.

MavenLibrary

Nome do campo Tipo Descrição
coordinates STRING Coordenadas Maven no estilo Gradle. Por exemplo: org.jsoup:jsoup:1.7.2. Este campo é necessário.
repo STRING Repositório do Maven do qual instalar o pacote Maven. Se omitido, os pacotes do repositório central do Maven e do Spark serão pesquisados.
exclusions Uma matriz de STRING Lista de dependências a serem excluídas. Por exemplo: ["slf4j:slf4j", "*:hadoop-client"].

Exclusões de dependência do Maven: https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html.

NewCluster

Nome do campo Tipo Descrição
num_workers OU autoscale INT32 OU AutoScale Se a configuração for num_workers, o número de nós de trabalho que esse cluster deverá ter. Um cluster possui um driver do Spark e num_workers executores para um total de num_workers + 1 nós do Spark.

Observação: quando as propriedades de um cluster são lidas, esse campo reflete o número desejado de trabalhos em vez do número atual real de trabalhos. Por exemplo, se um cluster for redimensionado de cinco para dez trabalhos, esse campo será imediatamente atualizado para refletir o tamanho de destino de dez trabalhos, enquanto os trabalhos listados em spark_info aumentarão gradualmente de cinco para dez, à medida que os novos nós forem provisionados.

Se a configuração for autoscale, serão necessários parâmetros para aumentar e diminuir automaticamente os clusters de acordo com a carga.
spark_version STRING A versão do Spark do cluster. Uma lista de versões disponíveis do Spark pode ser recuperada por meio da chamada GET 2.0/clusters/spark-versions. Este campo é necessário.
spark_conf SparkConfPair Um objeto que contém um conjunto opcional de pares chave-valor de configuração do Spark especificado pelo usuário. Transmita também uma cadeia de caracteres de opções extras de JVM para o driver e os executores por meio de
spark.driver.extraJavaOptions e spark.executor.extraJavaOptions, respectivamente.

Exemplos de configurações do Spark:
{"spark.speculation": true, "spark.streaming.ui.retainedBatches": 5} ou
{"spark.driver.extraJavaOptions": "-verbose:gc -XX:+PrintGCDetails"}
node_type_id STRING Esse campo codifica, por meio de um único valor, os recursos disponíveis para cada um dos nós do Spark neste cluster. Por exemplo, os nós do Spark podem ser provisionados e otimizados para cargas de trabalho com uso intensivo de memória ou computação. Uma lista dos tipos de nós disponíveis pode ser recuperada por meio da chamada GET 2.0/clusters/list-node-types. Esse campo, o campo instance_pool_id ou uma política de cluster que especifica uma ID de tipo de nó ou ID do pool de instâncias é necessário.
driver_node_type_id STRING O tipo de nó do driver do Spark. Esse campo é opcional. Se ele não estiver definido, o tipo de nó de driver será definido com o mesmo valor que node_type_id definido acima.
custom_tags ClusterTag Um objeto que contém um conjunto de marcas para recursos de cluster. O Databricks marca todos os recursos de cluster (como VMs) com essas marcas, além de default_tags.

Observação:

* Não há suporte a marcas em tipos de nós herdados, por exemplo, com otimização para computação e com otimização de memória
* O Databricks permite, no máximo, 45 marcas personalizadas
cluster_log_conf ClusterLogConf A configuração usada para fornecer logs do Spark para um destino de armazenamento de longo prazo. Somente um destino pode ser especificado para um cluster. Se a configuração for fornecida, os logs serão entregues ao destino a cada 5 mins. O destino dos logs do driver é <destination>/<cluster-id>/driver, enquanto o destino dos logs do executor é <destination>/<cluster-id>/executor.
init_scripts Uma matriz de InitScriptInfo A configuração usada para armazenar scripts de inicialização. Qualquer número de scripts pode ser especificado. Os scripts são executados em sequência na ordem fornecida. Se cluster_log_conf for especificado, os logs do script init serão enviados para
<destination>/<cluster-id>/init_scripts.
spark_env_vars SparkEnvPair Um objeto que contém um conjunto de pares chave-valor de variável de ambiente especificado pelo usuário. O par chave-valor do formulário (X, Y) é exportado como está (ou seja,
export X='Y') quando o driver e os trabalhos são iniciados.

Para especificar um conjunto adicional de SPARK_DAEMON_JAVA_OPTS, recomendamos acrescentá-los a $SPARK_DAEMON_JAVA_OPTS, conforme mostrado no exemplo a seguir. Isso faz com que todas as variáveis de ambiente padrão gerenciadas pelo Databricks também sejam incluídas.

Exemplos de variáveis de ambiente do Spark:
{"SPARK_WORKER_MEMORY": "28000m", "SPARK_LOCAL_DIRS": "/local_disk0"} ou
{"SPARK_DAEMON_JAVA_OPTS": "$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true"}
enable_elastic_disk BOOL Dimensionamento automático do armazenamento local: quando essa opção estiver habilitada, esse cluster adquirirá dinamicamente espaço em disco adicional quando os trabalhos do Spark estiverem com pouco espaço em disco. Confira Habilitar o dimensionamento automático do armazenamento local para obter detalhes.
driver_instance_pool_id STRING O ID opcional do pool de instâncias a ser usado para o nó do driver. Você também precisa especificar instance_pool_id. Consulte a API dos Pools de Instância para obter detalhes.
instance_pool_id STRING O ID opcional do pool de instâncias a ser usado para os nós de cluster. Se driver_instance_pool_id estiver presente,
instance_pool_id só será usado para nós de trabalho. Caso contrário, ele será usado para o driver e os nós de trabalho. Consulte a API dos Pools de Instância para obter detalhes.

NotebookOutput

Nome do campo Tipo Descrição
result STRING O valor transmitido a dbutils.notebook.exit (). O Azure Databricks restringe essa API para retornar os primeiros 1 MB do valor. Para um resultado maior, seu trabalho pode armazenar os resultados em um serviço de armazenamento em nuvem. Esse campo estará ausente se dbutils.notebook.exit() nunca tiver sido chamado.
truncated BOOLEAN Se o resultado foi truncado ou não.

NotebookTask

Todas as células de saída estão sujeitas ao tamanho de 8 MB. Se a saída de uma célula tiver um tamanho maior, o restante da execução será cancelado e a execução será marcada como com falha. Nesse caso, parte da saída de conteúdo de outras células também poderá estar ausente.

Se você precisar de ajuda para encontrar a célula que está além do limite, execute o notebook em um cluster de uso geral e use esta técnica de salvamento automático do notebook.

Nome do campo Tipo Descrição
notebook_path STRING O caminho absoluto do notebook a ser executado no Workspace do Azure Databricks. Esse caminho deve começar com uma barra. Esse campo é obrigatório.
revision_timestamp LONG O carimbo de data/hora da revisão do notebook.
base_parameters Um mapa de ParamPair Parâmetros de base a serem usados para cada execução desse trabalho. Se a execução for iniciada por uma chamada para run-now com parâmetros especificados, os dois mapas de parâmetros serão mesclados. Se a mesma chave for especificada em base_parameters e em run-now, o valor de run-now será usado.

Use Passar contexto sobre execuções de trabalho em tarefas de trabalho para definir parâmetros que contêm informações sobre execuções de trabalho.

Se o notebook usar um parâmetro que não está especificado nos base_parameters do trabalho ou run-now substituir parâmetros, o valor padrão do notebook será utilizado.

Recupere esses parâmetros em um notebook usando dbutils.widgets.get.

ParamPair

Parâmetros baseados em nome para trabalhos que executam tarefas de notebook.

Importante

Os campos nessa estrutura de dados aceitam apenas caracteres latinos (conjunto de caracteres ASCII). O uso de caracteres não ASCII retornará um erro. Entre os exemplos de caracteres não ASCII inválidos estão o chinês, os kanjis do japonês e os emojis.

Type Descrição
STRING Nome do parâmetro. Transmita a dbutils.widgets.get para recuperar o valor.
STRING Valor de parâmetro.

PipelineTask

Nome do campo Tipo Descrição
pipeline_id STRING O nome completo da tarefa de pipeline do Delta Live Tables a ser executada.

PythonPyPiLibrary

Nome do campo Tipo Descrição
package STRING O nome do pacote PyPI a ser instalado. Também há suporte para uma especificação de versão exata opcional. Exemplos: simplejson e simplejson==3.8.0 Este campo é necessário.
repo STRING O repositório onde o pacote pode ser encontrado. Se não for especificado, o índice pip padrão será usado.

RCranLibrary

Nome do campo Tipo Descrição
package STRING O nome do pacote CRAN a ser instalado. Este campo é necessário.
repo STRING O repositório onde o pacote pode ser encontrado. Se não for especificado, o repositório do CRAN padrão será usado.

Run

Todas as informações sobre uma execução, exceto sua saída. A saída pode ser recuperada separadamente com o método getRunOutput.

Nome do campo Tipo Descrição
job_id INT64 O identificador canônico do trabalho que contém essa execução.
run_id INT64 O identificador canônico da execução. Esse ID é exclusivo em todas as execuções de todos os trabalhos.
creator_user_name STRING O nome de usuário do criador. Esse campo não será incluído na resposta se o usuário já tiver sido excluído.
number_in_job INT64 O número de sequência dessa execução dentre todas as execuções do trabalho. Esse valor começa em 1.
original_attempt_run_id INT64 Se essa é uma nova tentativa de uma tentativa de execução anterior, esse campo contém o run_id da tentativa original; caso contrário, é o mesmo run_id.
state RunState O resultado e os estados de ciclo de vida da execução.
schedule CronSchedule A agenda Cron que disparou essa operação se ela foi disparada pelo agendador periódico.
task JobTask A tarefa executada pela execução, se houver.
cluster_spec ClusterSpec Um instantâneo da especificação de cluster do trabalho quando a execução foi criada.
cluster_instance ClusterInstance O cluster usado para essa execução. Se houver especificação para a execução usar um novo cluster, esse campo será definido depois que o serviço Trabalhos tiver solicitado um cluster para a execução.
overriding_parameters RunParameters Os parâmetros usados para essa execução.
start_time INT64 A hora em que essa execução foi iniciada em milissegundos de época (milissegundos desde 1/1/1970 UTC). Essa pode não ser a hora em que a tarefa de trabalho começa a ser executada, por exemplo, se o trabalho estiver agendado para execução em um novo cluster, essa será a hora em que a chamada de criação do cluster foi feita.
setup_duration INT64 O tempo necessário para configurar o cluster em milissegundos. Para as execuções feitas em novos clusters, esse é o tempo de criação do cluster; para as execuções feitas em clusters existentes, o tempo deve ser muito curto.
execution_duration INT64 O tempo em milissegundos que levou para executar os comandos no JAR ou notebook até eles serem concluídos, falharem, atingirem o tempo limite, serem cancelados ou encontrarem um erro inesperado.
cleanup_duration INT64 O tempo em milissegundos necessário para terminar o cluster e limpar todos os artefatos associados. A duração total da execução é a soma de setup_duration, execution_duration e cleanup_duration.
end_time INT64 A hora em que essa execução terminou em milissegundos de época (milissegundos desde 1/1/1970 UTC). Esse campo será definido como 0 se o trabalho ainda estiver em execução.
trigger TriggerType O tipo de gatilho que disparou essa execução.
run_name STRING Um nome opcional para a execução. O valor padrão é Untitled. O tamanho máximo permitido é de 4096 bytes na codificação UTF-8.
run_page_url STRING A URL para a página de detalhes da execução.
run_type STRING O tipo de execução.

* JOB_RUN: execução de trabalho normal. Uma execução criada com Executar agora.
* WORKFLOW_RUN: execução de fluxo de trabalho. Uma execução criada com dbutils.notebook.run.
* SUBMIT_RUN: execução de envio. Uma execução criada com Executar agora.
attempt_number INT32 O número de sequência dessa tentativa de execução em uma sequência de trabalho disparada. A tentativa inicial de uma execução tem um attempt_number de 0. Se a execução inicial falhar e o trabalho tiver uma política de repetição (max_retries> 0), as execuções subsequentes serão criadas com um original_attempt_run_id do ID da tentativa original e um attempt_number incremental. As execuções são tentadas novamente apenas até terem êxito, e o attempt_number máximo é o mesmo valor de max_retries do trabalho.

RunJobTask

Nome do campo Tipo Descrição
job_id INT32 Identificador exclusivo da etapa de trabalho. Este campo é necessário.

RunLifeCycleState

O estado do ciclo de vida de uma execução. As transições de estado permitidas são:

  • PENDING ->RUNNING ->TERMINATING ->TERMINATED
  • PENDING ->SKIPPED
  • PENDING ->INTERNAL_ERROR
  • RUNNING ->INTERNAL_ERROR
  • TERMINATING ->INTERNAL_ERROR
Estado Descrição
PENDING A execução foi disparada. Se ainda não existe uma execução ativa do mesmo trabalho, o cluster e o contexto de execução estão sendo preparados. Se já houver uma execução ativa do mesmo trabalho, a execução fará a transição imediatamente para o estado SKIPPED sem preparar nenhum recurso.
RUNNING A tarefa dessa execução está sendo realizada.
TERMINATING A tarefa dessa execução foi concluída e o cluster e o contexto de execução estão sendo limpos.
TERMINATED A tarefa dessa execução foi concluída e o cluster e o contexto de execução foram limpos. Esse estado é terminal.
SKIPPED Essa execução foi anulada porque uma versão anterior do mesmo trabalho já estava ativa. Esse estado é terminal.
INTERNAL_ERROR Um estado excepcional que indica uma falha no serviço Trabalhos, por exemplo, falha de rede por um longo período. Se uma execução em um novo cluster terminar no estado INTERNAL_ERROR, o serviço Trabalhos terminará o cluster assim que possível. Esse estado é terminal.

RunParameters

Parâmetros para essa execução. Somente um dos jar_params, python_params ou notebook_params deve ser especificado na solicitação run-now, dependendo do tipo de tarefa de trabalho. Trabalhos com tarefa JAR do Spark ou Python usam uma lista de parâmetros baseados em posição; os trabalhos com tarefas de notebook usam um mapa de valores-chave.

Nome do campo Tipo Descrição
jar_params Uma matriz de STRING Uma lista de parâmetros para trabalhos com tarefas de JAR do Spark, por exemplo, "jar_params": ["john doe", "35"]. Os parâmetros serão usados para invocar a função principal da classe principal especificada na tarefa de JAR do Spark. Se não forem especificados em run-now, ela usará como padrão uma lista vazia. Não é possível especificar jar_params em conjunto com notebook_params. A representação JSON do campo (ou seja, {"jar_params":["john doe","35"]}) não pode exceder 10.000 bytes.

Use Passar contexto sobre execuções de trabalho em tarefas de trabalho para definir parâmetros que contêm informações sobre execuções de trabalho.
notebook_params Um mapa de ParamPair Um mapa de chaves para valores de trabalhos com tarefas de notebook, por exemplo,
"notebook_params": {"name": "john doe", "age": "35"}. O mapa é transmitido ao notebook e pode ser acessado por meio da função dbutils.widgets.get.

Se não for especificado em run-now, a execução disparada usará os parâmetros de base do trabalho.

Não é possível especificar notebook_params em conjunto com jar_params.

Use Passar contexto sobre execuções de trabalho em tarefas de trabalho para definir parâmetros que contêm informações sobre execuções de trabalho.

A representação JSON do campo (ou seja,
{"notebook_params":{"name":"john doe","age":"35"}}) não pode exceder 10.000 bytes.
python_params Uma matriz de STRING Uma lista de parâmetros para trabalhos com tarefas do Python, por exemplo, "python_params": ["john doe", "35"]. Os parâmetros são transmitidos ao arquivo Python como parâmetros de linha de comando. Se especificado em run-now, ele substituiria os parâmetros especificados na configuração do trabalho. A representação JSON do campo (ou seja, {"python_params":["john doe","35"]}) não pode exceder 10.000 bytes.

Use Passar contexto sobre execuções de trabalho em tarefas de trabalho para definir parâmetros que contêm informações sobre execuções de trabalho.

> [!IMPORTANTE] >> Esses parâmetros aceitam apenas caracteres latinos (conjunto de caracteres ASCII). >O uso de caracteres não ASCII retornará um erro. Entre os exemplos de caracteres não ASCII > inválidos estão o chinês, os kanjis do japonês e os emojis.
spark_submit_params Uma matriz de STRING Uma lista de parâmetros para trabalhos com tarefa de envio do Spark, por exemplo,
"spark_submit_params": ["--class", "org.apache.spark.examples.SparkPi"]. Os parâmetros são transmitidos ao script spark-submit como parâmetros de linha de comando. Se especificado em run-now, ele substituiria os parâmetros especificados na configuração do trabalho. A representação JSON do campo (ou seja, {"python_params":["john doe","35"]}) não pode exceder 10.000 bytes.

Use Passar contexto sobre execuções de trabalho em tarefas de trabalho para definir parâmetros que contêm informações sobre execuções de trabalho.

> [!IMPORTANTE] >> Esses parâmetros aceitam apenas caracteres latinos (conjunto de caracteres ASCII). >O uso de caracteres não ASCII retornará um erro. Entre os exemplos de caracteres não ASCII > inválidos estão o chinês, os kanjis do japonês e os emojis.

RunResultState

O estado de resultado da execução.

  • Se life_cycle_state = TERMINATED: se a execução tiver uma tarefa, o resultado ficará garantidamente disponível e indicará o resultado da tarefa.
  • Se life_cycle_state = PENDING, RUNNING ou SKIPPED, o estado do resultado não ficará disponível.
  • Se life_cycle_state = TERMINATING ou lifecyclestate = INTERNAL_ERROR: o estado do resultado ficará disponível se a execução tiver uma tarefa e estiver gerenciada para iniciá-la.

Uma vez disponível, o estado do resultado nunca será alterado.

Estado Descrição
SUCCESS A tarefa foi concluída com êxito.
FAILED A tarefa foi concluída com um erro.
TIMEDOUT A execução foi interrompida depois de atingir o tempo limite.
CANCELED A execução foi cancelada por solicitação do usuário.

RunState

Nome do campo Tipo Descrição
life_cycle_state RunLifeCycleState Uma descrição da localização atual da execução em seu ciclo de vida. Esse campo está sempre disponível na resposta.
result_state RunResultState O estado de resultado de uma execução. Se não estiver disponível, a resposta não incluirá esse campo. Confira RunResultState para obter detalhes sobre a disponibilidade de result_state.
user_cancelled_or_timedout BOOLEAN Se uma execução foi cancelada manualmente por um usuário ou pelo agendador porque o tempo limite da execução foi atingido.
state_message STRING Uma mensagem descritiva sobre o estado atual. Esse campo não é estruturado, e o formato exato está sujeito a alterações.

SparkConfPair

Pares chave-valor de configuração do Spark.

Type Descrição
STRING Um nome de propriedade de configuração.
STRING O valor da propriedade de configuração.

SparkEnvPair

Pares chave-valor de variável de ambiente do Spark.

Importante

Quando as variáveis de ambiente são especificadas em um cluster de trabalho, os campos dessa estrutura de dados aceitam apenas caracteres latinos (conjunto de caracteres ASCII). O uso de caracteres não ASCII retornará um erro. Entre os exemplos de caracteres não ASCII inválidos estão o chinês, os kanjis do japonês e os emojis.

Type Descrição
STRING O nome de uma variável de ambiente.
STRING O valor da variável de ambiente.

SparkJarTask

Nome do campo Tipo Descrição
jar_uri STRING Preterido desde 04/2016. Forneça um jar por meio do campo libraries. Para ver um exemplo, confira Create.
main_class_name STRING O nome completo da classe que contém o método principal a ser executado. Essa classe deve estar contida em um JAR fornecido como uma biblioteca.

O código deve usar SparkContext.getOrCreate para obter um contexto do Spark; caso contrário, as execuções do trabalho falharão.
parameters Uma matriz de STRING Parâmetros transmitidos ao método principal.

Use Passar contexto sobre execuções de trabalho em tarefas de trabalho para definir parâmetros que contêm informações sobre execuções de trabalho.

SparkPythonTask

Nome do campo Tipo Descrição
python_file STRING O URI do arquivo Python a ser executado. Há suporte apenas a caminhos DBFS. Esse campo é obrigatório.
parameters Uma matriz de STRING Parâmetros de linha de comando transmitidos ao arquivo Python.

Use Passar contexto sobre execuções de trabalho em tarefas de trabalho para definir parâmetros que contêm informações sobre execuções de trabalho.

SparkSubmitTask

Importante

  • Você somente pode invocar tarefas de envio do Spark em novos clusters.
  • Na especificação new_cluster, tanto libraries quanto spark_conf não tem suporte. Use --jars e --py-files para adicionar bibliotecas Java e Python e --conf para definir a configuração do Spark.
  • master, deploy-modee executor-cores são configurados automaticamente pelo Azure Databricks; você não pode especificá-los em parâmetros.
  • Por padrão, o trabalho de envio do Spark usa toda a memória disponível (exceto a memória reservada para os serviços do Azure Databricks). Você pode definir --driver-memorye --executor-memory como um valor menor a fim de deixar algum espaço para uso fora do heap.
  • Os argumentos --jars, --py-files e --files dão suporte a caminhos DBFS.

Por exemplo, supondo que o JAR seja carregado no DBFS, você poderá executar SparkPi com a definição dos parâmetros a seguir.

{
  "parameters": [
    "--class",
    "org.apache.spark.examples.SparkPi",
    "dbfs:/path/to/examples.jar",
    "10"
  ]
}
Nome do campo Tipo Descrição
parameters Uma matriz de STRING Parâmetros de linha de comando transmitidos ao envio do Spark.

Use Passar contexto sobre execuções de trabalho em tarefas de trabalho para definir parâmetros que contêm informações sobre execuções de trabalho.

TriggerType

São os tipos de gatilhos que podem disparar uma execução.

Type Descrição
PERIODIC Agendamentos que disparam execuções periodicamente, por exemplo, uma agenda Cron.
ONE_TIME Gatilhos únicos que acionam uma única execução. Isso ocorre quando você disparou uma única execução sob demanda por meio da interface do usuário ou da API.
RETRY Indica uma execução que é disparada como uma nova tentativa de uma execução anterior com falha. Isso ocorre quando você solicita nova execução do trabalho em caso de falhas.

ViewItem

O conteúdo exportado está no formato HTML. Por exemplo, se a exibição a ser exportada for dashboards, uma cadeia de caracteres HTML será retornada para cada dashboard.

Nome do campo Tipo Descrição
content STRING Conteúdo da exibição.
name STRING Nome do item de exibição. No caso da exibição de código, o nome do notebook. No caso da exibição de dashboard, o nome do dashboard.
type ViewType Tipo do item de exibição.

ViewType

Type Descrição
NOTEBOOK Item de exibição do notebook.
DASHBOARD Item de exibição do dashboard.

ViewsToExport

Exibir para exportar: código, todos os dashboards ou tudo.

Type Descrição
CODE Exibição de código do notebook.
DASHBOARDS Todas as exibições de dashboard do notebook.
ALL Todas as exibições do notebook.

Webhook

Nome do campo Tipo Descrição
id STRING Identificador referenciando um destino de notificação do sistema. Esse campo é obrigatório.

WebhookNotifications

Nome do campo Tipo Descrição
on_start Uma matriz de Webhook Uma lista de destinos do sistema a serem notificados quando uma execução for iniciada. Se não for especificada na criação, redefinição ou atualização do trabalho, a lista estará vazia e as notificações não serão enviadas. No máximo três destinos podem ser especificados para a propriedade on_start.
on_success Uma matriz de Webhook Uma lista de destinos do sistema a serem notificados quando uma execução for concluída com êxito. Uma execução será considerada concluída com êxito se terminar com TERMINATEDlife_cycle_state e um SUCCESSFULresult_state. Se não for especificada na criação, redefinição ou atualização do trabalho, a lista estará vazia e as notificações não serão enviadas. No máximo três destinos podem ser especificados para a propriedade on_success.
on_failure Uma matriz de Webhook Uma lista de destinos do sistema a serem notificados quando uma execução for concluída sem êxito. Uma execução é considerada concluída sem êxito quando termina com INTERNAL_ERROR
life_cycle_state ou um SKIPPED, FAILED ou TIMED_OUTresult_state. Se não for especificada na criação, redefinição ou atualização do trabalho, a lista estará vazia e as notificações não serão enviadas. No máximo três destinos podem ser especificados para a propriedade on_failure.
on_duration_warning_threshold_exceeded Uma matriz de Webhook Uma lista opcional de endereços de email a serem notificados quando a duração de uma execução exceder o limite especificado para a métrica RUN_DURATION_SECONDS no campo health. No máximo três destinos podem ser especificados para a propriedade on_duration_warning_threshold_exceeded.

WorkspaceStorageInfo

Informações de armazenamento do workspace.

Nome do campo Tipo Descrição
destination STRING Destino do arquivo. Exemplo: /Users/someone@domain.com/init_script.sh