Partilhar via

Atualização da API de trabalhos 2.0 para 2.1

  • Artigo

Agora pode orquestrar múltiplas tarefas com o Azure Databricks jobs. Este artigo detalha as alterações na API de Trabalhos que oferecem suporte a trabalhos com várias tarefas e inclui orientações para ajudá-lo a update seus clientes de API existentes para funcionar com este novo recurso.

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

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

As APIs de trabalhos 2.0 e 2.1 agora suportam a solicitação update. Use a solicitação update para alterar um trabalho existente em vez da solicitação reset para minimizar as alterações entre trabalhos de formato de tarefa única e trabalhos de formato de várias tarefas.

Alterações na API

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

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

A API de trabalhos 2.1 suporta o formato multitarefa. Todas as solicitações da API 2.1 devem estar em conformidade com esse formato e as respostas são estruturadas nesse formato.

A API de trabalhos 2.0 é atualizada com um campo adicional para oferecer suporte a trabalhos de formato multitarefa. Exceto no caso de where, os exemplos neste documento usam o 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 trabalho de 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 suporta a configuração de clusters de nível de tarefa ou um ou mais clusters de tarefas compartilhadas:

  • Um cluster de nível de tarefa é criado e iniciado quando uma tarefa é iniciada e terminada quando a tarefa é concluída.
  • Um cluster de tarefas compartilhadas permite que várias tarefas no mesmo trabalho usem o cluster. O cluster é criado e iniciado quando a primeira tarefa usando o cluster é iniciada e terminada após a conclusão da última tarefa usando o cluster. Um cluster de trabalho compartilhado não é encerrado quando ocioso, mas termina somente depois que todas as tarefas que o usam são concluídas. Várias tarefas não dependentes que compartilham um cluster podem começar ao mesmo tempo. Se um cluster de tarefas compartilhadas falhar ou for encerrado antes que todas as tarefas sejam concluídas, um novo cluster será criado.

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

Observação

Se uma tarefa tiver dependências de biblioteca, você deverá configurá-las nas configurações do campo task; As bibliotecas não podem ser configuradas em uma configuração de cluster de trabalho compartilhado. 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 trabalhos de formato de tarefa única, a estrutura de dados JobSettings permanece inalterada, exceto para a adição do campo format. Nenhuma matriz TaskSettings está incluída e as configurações de 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 trabalhos de formato de tarefa única.

Um exemplo de documento JSON que representa um trabalho de formato de tarefa única para a 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 da API

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

Nesta secção:

Criar

Para criar um trabalho de tarefa única por meio da operação Criar um novo trabalho (POST /jobs/create) na API de Trabalhos, não é necessário alterar os clientes existentes.

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

Observação

Um máximo de 100 tarefas pode ser especificado por trabalho.

{
  "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
    }
  ]
}

Executa enviar

Para submeter uma execução única de um trabalho no formato de tarefa única com a operação Criar e acionar uma execução única (POST /runs/submit) na API de Trabalhos, não é necessário alterar os clientes já existentes.

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

Update

Para update um formato de tarefa única com o Parcialmente update uma operação de trabalho (POST /jobs/update) na API de Trabalhos, não é necessário alterar os clientes existentes.

Para update as configurações de um trabalho de formato multitarefa, você deve usar o campo task_key exclusivo para identificar novas configurações de task. Consulte Criar para ver um exemplo JobSettings que especifica várias tarefas.

Reset

Para substituir as configurações de um trabalho de formatação de tarefa única pela operação Substituir todas as configurações de uma tarefa de trabalho (POST /jobs/reset) na API de Trabalhos, não é necessário modificar os clientes existentes.

Para sobrepor as definições de um trabalho de formato multitarefa, especifique uma estrutura de dados JobSettings com uma série de estruturas de dados TaskSettings. Consulte Criar para ver um exemplo JobSettings que especifica várias tarefas.

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

List

Para trabalhos de formato de tarefa única, nenhuma alteração de cliente é necessária para processar a resposta do List todos os trabalhos operação (GET /jobs/list) na API de Trabalhos.

Para trabalhos de formato multitarefa, a maioria das configurações é definida no nível da tarefa e não no nível da tarefa. A configuração do cluster pode ser set no nível da tarefa ou do trabalho. Para modificar clientes para aceder às configurações de cluster ou de tarefa para um trabalho de formato multitarefa retornado na estrutura Job:

  • Analise o campo job_id para a tarefa de formato multitarefa.
  • Passe o job_id para a operação de trabalho Get de (GET /jobs/get) na Jobs API para obter detalhes do trabalho. Consulte Get para obter um exemplo de resposta da chamada de API do Get para um trabalho em formato de multitarefa.

O exemplo a seguir mostra uma resposta que contém trabalhos de formato de tarefa única e multitarefa. Este exemplo é para a 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"
    }
  ]
}

Get

Para trabalhos de formato de tarefa única, nenhuma alteração do cliente é necessária para processar a resposta de uma operação de trabalho do () na API de Trabalhos.

Trabalhos de formato multitarefa retornam uma matriz de estruturas de dados task contendo configurações de tarefas. Se você precisar de acesso aos detalhes de nível de tarefa, precisará modificar seus clientes para iterar através da matriz tasks e extrair campos obrigatórios.

A seguir mostra um exemplo de resposta da chamada de API Get para um trabalho 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"
}

Funciona get

Para trabalhos de formato de tarefa única, nenhuma alteração de cliente é necessária para processar a resposta do Get uma operação de de execução de trabalho (GET /jobs/runs/get) na API de Trabalhos.

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

  • Itere através de cada uma das tarefas.
  • Analise o run_id para cada tarefa.
  • Chame o Get a saída de uma operação de execução (GET /jobs/runs/get-output) com run_id a get detalhes sobre a execução para cada tarefa. Segue-se um exemplo de resposta a este pedido:
{
  "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"
}

Executa saída de get

Para trabalhos no formato de tarefa única, não são necessárias alterações no cliente para processar a resposta na Get, a saída de uma operação de execução (GET /jobs/runs/get-output) na API de Trabalhos.

Para trabalhos de tarefa múltipla, invocar Runs get output numa execução pai resulta em um erro, uma vez que o resultado da execução está disponível apenas para tarefas individuais. Para get a saída e os metadados para um trabalho em formato multitarefa:

Funciona list

Para trabalhos de formato de tarefa única, não são necessárias alterações do cliente para processar a resposta dos List realizados para uma operação de trabalho (GET /jobs/runs/list).

Para tarefas em formato multitarefa, retorna-se um array vazio de tasks. Passe o run_id para a operação de execução do trabalho Get (GET /jobs/runs/get) para recuperar as tarefas. A seguir mostra um exemplo de resposta da chamada de API Runs list para um trabalho 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
}