Atualizando da API Jobs 2.0 para 2.1

Agora você pode orquestrar múltiplas tarefas com Databricks Job. Este artigo detalha as alterações na API Jobs que suportam Job com múltiplas tarefas e fornece orientação para ajudá-lo a atualizar seus clientes API existentes para trabalhar com esse novo recurso.

Databricks recomenda Jobs API 2.1 para seus scripts e clientes de API, especialmente ao usar trabalhos com várias tarefas.

Este artigo refere-se a Job definido com uma única tarefa como formato de tarefa única e Job definido com várias tarefas como formato multitarefa.

A API de tarefas 2.0 e 2.1 agora oferece suporte à solicitação de atualização . Use a solicitação update para alterar um Job existente em vez da solicitação Reset para minimizar as alterações entre Job de formato de tarefa única e o Job de formato multitarefa .

alterações de API

A API de Jobs agora define um objeto TaskSettings para capturar configurações para cada tarefa em um Job. Para Job de formato multitarefa, o campo tasks, uma matriz de estruturas de dados TaskSettings, é incluído no objeto JobSettings. Alguns campos que anteriormente faziam parte de JobSettings agora fazem parte das configurações de tarefa para Job em formato multitarefa. JobSettings também é atualizado para incluir o campo format . O campo format indica o formato da Job e é um valor STRING definido como SINGLE_TASK ou MULTI_TASK.

Você precisa atualizar seus clientes de API existentes para essas alterações em JobSettings para trabalhos de formato multitarefa. Consulte o guia do cliente API para obter mais informações sobre as alterações necessárias.

Jobs API 2.1 oferece suporte ao formato multitarefa. Todas as solicitações da API 2.1 devem estar em conformidade com o formato multitarefa e as respostas são estruturadas no formato multitarefa. Novos recursos são lançados primeiro para a API 2.1.

O Jobs API 2.0 foi atualizado com um campo adicional para dar suporte ao formato multitarefa Job. Exceto onde indicado, os exemplos neste documento usam API 2.0. No entanto, o Databricks recomenda a API 2.1 para scripts e clientes de API novos e existentes.

Um exemplo de documento JSON que representa um Job em formato multitarefa para API 2.0 e 2.1:

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "tasks": [
      {
        "task_key": "clean_data",
        "description": "Clean and prepare the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_data",
        "description": "Perform an analysis of the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

A API de trabalhos 2.1 oferece suporte à configuração de clusters de nível de tarefa ou um ou mais clusters Job compartilhados:

  • Um clusters de nível de tarefa é criado e começa quando uma tarefa começa e termina quando a tarefa é concluída.

  • Um clusters Job compartilhado permite que várias tarefas no mesmo Job usem os clusters. Os clusters são criados e começam quando a primeira tarefa usando os clusters começa e termina após a conclusão da última tarefa usando os clusters . Um clusters Job compartilhado não é encerrado quando o parado, mas é encerrado somente após a conclusão de todas as tarefas que o utilizam. Múltiplas tarefas não dependentes de compartilhamento de clusters podem começar ao mesmo tempo. Se um clusters Job compartilhado falhar ou for encerrado antes que todas as tarefas sejam concluídas, um novo clusters será criado.

Para configurar clusters Job compartilhadas, inclua uma matriz JobCluster no objeto JobSettings. Você pode especificar no máximo 100 clusters por Job. Veja a seguir um exemplo de resposta da API 2.1 para um Job configurado com dois clusters compartilhados:

Observação

Se uma tarefa tiver dependências de biblioteca, você deve configurar as bibliotecas nas configurações do campo task; as bibliotecas não podem ser configuradas em uma configuração clusters Job compartilhados. No exemplo a seguir, o campo libraries na configuração da tarefa ingest_orders demonstra a especificação de uma dependência de biblioteca.

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "job_clusters": [
      {
        "job_cluster_key": "default_cluster",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "i3.xlarge",
          "spark_conf": {
            "spark.speculation": true
          },
          "aws_attributes": {
            "availability": "SPOT",
            "zone_id": "us-west-2a"
          },
          "autoscale": {
            "min_workers": 2,
            "max_workers": 8
          }
        }
      },
      {
        "job_cluster_key": "data_processing_cluster",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "r4.2xlarge",
          "spark_conf": {
            "spark.speculation": true
          },
          "aws_attributes": {
            "availability": "SPOT",
            "zone_id": "us-west-2a"
          },
          "autoscale": {
            "min_workers": 8,
            "max_workers": 16
          }
        }
      }
    ],
    "tasks": [
      {
        "task_key": "ingest_orders",
        "description": "Ingest order data",
        "depends_on": [ ],
        "job_cluster_key": "auto_scaling_cluster",
        "spark_jar_task": {
          "main_class_name": "com.databricks.OrdersIngest",
          "parameters": [
            "--data",
            "dbfs:/path/to/order-data.json"
          ]
        },
        "libraries": [
          {
            "jar": "dbfs:/mnt/databricks/OrderIngest.jar"
          }
        ],
        "timeout_seconds": 86400,
        "max_retries": 3,
        "min_retry_interval_millis": 2000,
        "retry_on_timeout": false
      },
      {
        "task_key": "clean_orders",
        "description": "Clean and prepare the order data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "job_cluster_key": "default_cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_orders",
        "description": "Perform an analysis of the order data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "job_cluster_key": "data_processing_cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

Para Job de formato de tarefa única, a estrutura de dados JobSettings permanece inalterada, exceto pela adição do campo format. Nenhuma matriz TaskSettings está incluída e as configurações da tarefa permanecem definidas no nível superior da estrutura de dados JobSettings . Você não precisará fazer alterações em seus clientes de API existentes para processar o formato de tarefa única Job.

Um exemplo de documento JSON que representa um Job de formato de tarefa única para API 2.0:

{
  "job_id": 27,
  "settings": {
    "name": "Example notebook",
    "existing_cluster_id": "1201-my-cluster",
    "libraries": [
      {
        "jar": "dbfs:/FileStore/jars/spark_examples.jar"
      }
    ],
    "email_notifications": {},
    "timeout_seconds": 0,
    "schedule": {
      "quartz_cron_expression": "0 0 0 * * ?",
      "timezone_id": "US/Pacific",
      "pause_status": "UNPAUSED"
    },
    "notebook_task": {
      "notebook_path": "/notebooks/example-notebook",
      "revision_timestamp": 0
    },
    "max_concurrent_runs": 1,
    "format": "SINGLE_TASK"
  },
  "created_time": 1504128821443,
  "creator_user_name": "user@databricks.com"
}

Guia do cliente API

Esta seção fornece diretrizes, exemplos e alterações necessárias para chamadas de API afetadas pelo novo recurso de formato multitarefa.

Criar

Para criar um Job em formato de tarefa única por meio das operações Criar um novo Job (POST /jobs/create) na API Jobs, não é necessário alterar os clientes existentes.

Para criar um Job em formato multitarefa, use o campo tasks em JobSettings para especificar as configurações de cada tarefa. O exemplo a seguir cria um Job com duas tarefas Notebook . Este exemplo é para API 2.0 e 2.1:

Observação

Um máximo de 100 tarefas podem ser especificadas por Job.

{
  "name": "Multi-task-job",
  "max_concurrent_runs": 1,
  "tasks": [
    {
      "task_key": "clean_data",
      "description": "Clean and prepare the data",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/clean-data"
      },
      "existing_cluster_id": "1201-my-cluster",
      "timeout_seconds": 3600,
      "max_retries": 3,
      "retry_on_timeout": true
    },
    {
      "task_key": "analyze_data",
      "description": "Perform an analysis of the data",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/analyze-data"
      },
      "depends_on": [
        {
          "task_key": "clean_data"
        }
      ],
      "existing_cluster_id": "1201-my-cluster",
      "timeout_seconds": 3600,
      "max_retries": 3,
      "retry_on_timeout": true
    }
  ]
}

execução submeter

Para enviar uma execução única de um Job em formato de tarefa única com Criar e acionar operações de execução única (POST /runs/submit) na API Jobs, não é necessário alterar os clientes existentes.

Para enviar uma execução única de uma Job em formato multitarefa, use o campo tasks em JobSettings para especificar as configurações de cada tarefa, incluindo clusters. Os clusters devem ser configurados no nível da tarefa ao enviar um Job em formato multitarefa porque a solicitação runs submit não oferece suporte a clusters de Job compartilhados. Consulte Criar para obter um exemplo JobSettings especificando várias tarefas.

Atualizar

Para atualizar um Job de formato de tarefa única com as operações Atualizar parcialmente um Job (POST /jobs/update) na API Jobs, não é necessário alterar os clientes existentes.

Para atualizar as configurações de um Job em formato multitarefa, você deve usar o campo task_key exclusivo para identificar novas configurações task. Consulte Criar para obter um exemplo JobSettings especificando várias tarefas.

Reset

Para substituir as configurações de um Job de formato de tarefa única com Substituir todas as configurações de operações Job (POST /jobs/reset) na API Jobs, não é necessário alterar os clientes existentes.

Para substituir as configurações de um Job de formato multitarefa, especifique uma estrutura de dados JobSettings com uma matriz de estruturas de dados TaskSettings. Consulte Criar para obter um exemplo JobSettings especificando várias tarefas.

Use Atualizar para alterar campos individuais sem alternar do formato de tarefa única para multitarefa.

Lista

Para Job no formato de tarefa única, nenhuma alteração do cliente é necessária para processar a resposta de Listar todas as operações Job (GET /jobs/list) na API Jobs.

Para Job no formato multitarefa, a maioria das configurações é definida no nível da tarefa e não no nível do Job . a configuração clusters pode ser definida no nível da tarefa ou Job . Para modificar os clientes para acessar clusters ou configurações de tarefa para um Job de formato multitarefa retornado na estrutura Job:

  • Analise o campo job_id para o Job de formato multitarefa.

  • Passe o job_id para as operações Get a Job (GET /jobs/get) na API Jobs para recuperar detalhes Job . Consulte Obter para obter um exemplo de resposta da chamada de API Get para um Job de formato multitarefa.

O exemplo a seguir mostra uma resposta contendo Job de formato de tarefa única e multitarefa. Este exemplo é para API 2.0:

{
  "jobs": [
    {
      "job_id": 36,
      "settings": {
        "name": "A job with a single task",
        "existing_cluster_id": "1201-my-cluster",
        "email_notifications": {},
        "timeout_seconds": 0,
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/example-notebook",
          "revision_timestamp": 0
        },
        "max_concurrent_runs": 1,
        "format": "SINGLE_TASK"
      },
      "created_time": 1505427148390,
      "creator_user_name": "user@databricks.com"
    },
    {
      "job_id": 53,
      "settings": {
        "name": "A job with multiple tasks",
        "email_notifications": {},
        "timeout_seconds": 0,
        "max_concurrent_runs": 1,
        "format": "MULTI_TASK"
      },
      "created_time": 1625841911296,
      "creator_user_name": "user@databricks.com"
    }
  ]
}

Pegar

Para Job no formato de tarefa única, nenhuma alteração do cliente é necessária para processar a resposta das operações Get a Job (GET /jobs/get) na API Jobs.

Job de formato multitarefa retorna uma matriz de estruturas de dados task contendo configurações de tarefa. Se você precisar de acesso aos detalhes de nível de tarefa, precisará modificar seus clientes para iterar por meio da matriz tasks e extrair os campos obrigatórios.

Veja a seguir um exemplo de resposta da chamada de API Get para um Job de formato multitarefa. Este exemplo é para API 2.0 e 2.1:

{
  "job_id": 53,
  "settings": {
    "name": "A job with multiple tasks",
    "email_notifications": {},
    "timeout_seconds": 0,
    "max_concurrent_runs": 1,
    "tasks": [
      {
        "task_key": "clean_data",
        "description": "Clean and prepare the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/clean-data"
        },
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      },
      {
        "task_key": "analyze_data",
        "description": "Perform an analysis of the data",
        "notebook_task": {
          "notebook_path": "/Users/user@databricks.com/analyze-data"
        },
        "depends_on": [
          {
            "task_key": "clean_data"
          }
        ],
        "existing_cluster_id": "1201-my-cluster",
        "max_retries": 3,
        "min_retry_interval_millis": 0,
        "retry_on_timeout": true,
        "timeout_seconds": 3600,
        "email_notifications": {}
      }
    ],
    "format": "MULTI_TASK"
  },
  "created_time": 1625841911296,
  "creator_user_name": "user@databricks.com",
  "run_as_user_name": "user@databricks.com"
}

execução get

Para Job no formato de tarefa única, nenhuma alteração do cliente é necessária para processar a resposta das operações de execução Get a Job (GET /jobs/runs/get) na API Jobs.

A resposta para uma execução Job em formato multitarefa contém uma matriz de TaskSettings. Para recuperar os resultados da execução de cada tarefa:

  • Repita cada uma das tarefas.

  • Analise o run_id para cada tarefa.

  • Chame Get the output for a run operações (GET /jobs/runs/get-output) com o run_id para obter detalhes sobre a execução de cada tarefa. Veja a seguir um exemplo de resposta desta solicitação:

{
  "job_id": 53,
  "run_id": 759600,
  "number_in_job": 7,
  "original_attempt_run_id": 759600,
  "state": {
    "life_cycle_state": "TERMINATED",
    "result_state": "SUCCESS",
    "state_message": ""
  },
  "cluster_spec": {},
  "start_time": 1595943854860,
  "setup_duration": 0,
  "execution_duration": 0,
  "cleanup_duration": 0,
  "trigger": "ONE_TIME",
  "creator_user_name": "user@databricks.com",
  "run_name": "Query logs",
  "run_type": "JOB_RUN",
  "tasks": [
    {
      "run_id": 759601,
      "task_key": "query-logs",
      "description": "Query session logs",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/log-query"
      },
      "existing_cluster_id": "1201-my-cluster",
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    },
    {
      "run_id": 759602,
      "task_key": "validate_output",
      "description": "Validate query output",
      "depends_on": [
        {
          "task_key": "query-logs"
        }
      ],
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/validate-query-results"
      },
      "existing_cluster_id": "1201-my-cluster",
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "format": "MULTI_TASK"
}

execução obter saída

Para Job no formato de tarefa única, nenhuma alteração do cliente é necessária para processar a resposta de Obter a saída para operações de execução (GET /jobs/runs/get-output) na API Jobs.

Para Job de formato multitarefa, chamar Runs get output em uma execução pai resulta em erro, pois a saída de execução está disponível apenas para tarefas individuais. Para obter a saída e os metadados para um Job em formato multitarefa:

lista de execução

Para Job no formato de tarefa única, nenhuma alteração do cliente é necessária para processar a resposta da execução da Lista para operações Job (GET /jobs/runs/list).

Para Job no formato multitarefa, um array tasks vazio é retornado. Passe o run_id para as operações Get a Job run (GET /jobs/runs/get) para recuperar a tarefa. Veja a seguir um exemplo de resposta da chamada de API Runs list para um Job de formato multitarefa:

{
  "runs": [
    {
      "job_id": 53,
      "run_id": 759600,
      "number_in_job": 7,
      "original_attempt_run_id": 759600,
      "state": {
          "life_cycle_state": "TERMINATED",
          "result_state": "SUCCESS",
          "state_message": ""
      },
      "cluster_spec": {},
      "start_time": 1595943854860,
      "setup_duration": 0,
      "execution_duration": 0,
      "cleanup_duration": 0,
      "trigger": "ONE_TIME",
      "creator_user_name": "user@databricks.com",
      "run_name": "Query logs",
      "run_type": "JOB_RUN",
      "tasks": [],
      "format": "MULTI_TASK"
    }
  ],
  "has_more": false
}