Compartilhar via

Atualização da API de Trabalhos 2.0 para 2.1

  • Artigo

Você pode orquestrar várias tarefas com trabalhos do Azure Databricks. Este artigo detalha as alterações na API de Trabalhos que dá suporte a trabalhos com várias tarefas e fornece diretrizes para ajudar você a atualizar seus clientes de API atuais para trabalhar com esse 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 de várias tarefas.

A API de Trabalhos 2.0 e 2.1 agora dá suporte à solicitação de atualização. Use a solicitação update para alterar um trabalho em vez da solicitação de redefinição para minimizar as alterações entre trabalhos de formato de tarefa única e trabalhos de formato de várias tarefas.

Alterações de API

Agora a API de Trabalhos define um objeto TaskSettings para capturar configurações para cada tarefa de um trabalho. Para trabalhos de formato de várias tarefas, o campo tasks, uma matriz de estruturas de dados TaskSettings, é incluído no objeto JobSettings. Alguns campos que fazem parte do JobSettings agora fazem parte das configurações de tarefa para trabalhos de formato de várias tarefas. JobSettings também foi atualizado para incluir o campo format. O campo format indica o formato do trabalho e é um valor STRING definido como SINGLE_TASK ou MULTI_TASK.

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

A API de Trabalhos 2.1 dá suporte ao formato de várias tarefas. Todas as solicitações da API 2.1 devem estar em conformidade com o formato de várias tarefas, e as respostas são estruturadas no formato de várias tarefas. Novos recursos são lançados para a API 2.1 primeiro.

A API de Trabalhos 2.0 foi atualizada com um campo extra para dar suporte a trabalhos de formato de várias tarefas. A menos que haja uma anotação, os exemplos deste documento usam a API 2.0. Mas o Databricks recomenda a API 2.1 para clientes e scripts de API novos e antigos.

Um documento JSON de exemplo que representa um trabalho de formato de várias tarefas para a 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 dá suporte à configuração de clusters de nível de tarefa ou a um ou mais clusters de trabalhos compartilhados:

  • Um cluster de nível de tarefa é criado e iniciado quando uma tarefa é iniciada e termina quando a tarefa é concluída.
  • Um cluster de trabalho compartilhado permite que várias tarefas do mesmo trabalho usem o cluster. O cluster é criado e iniciado quando a primeira tarefa que usa o cluster é iniciada e termina quando a última tarefa que usa o cluster é concluída. O cluster de trabalho compartilhado não é encerrado quando ocioso, e sim 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 trabalho compartilhado falha ou é encerrado antes da conclusão de todas as tarefas, um novo cluster é criado.

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

Observação

Se uma tarefa tem dependências de biblioteca, você precisa definir as bibliotecas nas configurações de campo task. As bibliotecas não podem ser definidas 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 pela 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 para processar trabalhos de formato de tarefa única.

Um documento JSON de exemplo 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 da API do cliente

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

Nesta seção:

Criar

Para criar um trabalho de formato de tarefa única com a operação Criar um novo trabalho (POST /jobs/create) na API de Trabalhos, você não precisa alterar os clientes.

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

Observação

É possível especificar até 100 tarefas 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 o envio

Para enviar uma única operação de um trabalho de formato de tarefa única com a operação Criar e disparar uma única operação (POST /runs/submit) na API de Trabalhos, você não precisa alterar os clientes.

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

Atualizar

Para atualizar um trabalho de formato de tarefa única com a operação Atualizar um trabalho parcialmente (POST /jobs/update) na API de Trabalhos, você não precisa alterar os clientes.

Para atualizar as configurações de um trabalho de formato de várias tarefas, use o campo exclusivo task_key para identificar novas configurações de task. Confira Criar para ver um JobSettings de exemplo que especifica várias tarefas.

Redefinir

Para substituir as configurações de um trabalho de formato de tarefa única com a operação Substituir todas as configurações de um trabalho (POST /jobs/reset) na API de Trabalhos, você não precisa alterar os clientes.

Para substituir as configurações de um trabalho de formato de várias tarefas, especifique uma estrutura de dados JobSettings com uma matriz de estruturas de dados TaskSettings. Confira Criar para ver um JobSettings de exemplo que especifica várias tarefas.

Use Atualizar para alterar campos individuais sem alternar do formato de tarefa única para o formato de várias tarefas.

Lista

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

Para trabalhos de formato de várias tarefas, a maioria das configurações é definida no nível da tarefa, e não no nível do trabalho. A configuração do cluster pode ser definida no nível da tarefa ou do trabalho. Para modificar clientes para acessar configurações de tarefa ou cluster em um trabalho de formato de várias tarefas retornado na estrutura Job:

  • Analise o campo job_id no trabalho de formato de várias tarefas.
  • Passe o job_id para a operação Obter um trabalho (GET /jobs/get) na API de Trabalhos para recuperar detalhes do trabalho. Confira Obter para ver um exemplo de resposta da chamada à API Get em um trabalho de formato de várias tarefas.

O exemplo a seguir mostra uma resposta que inclui trabalhos de formato de tarefa única e de várias tarefas. 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"
    }
  ]
}

Obter

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

Trabalhos de formato de várias tarefas retornam uma matriz de estrutura de dados task que contém configurações de tarefas. Se você precisa de acesso aos detalhes do nível da tarefa, modifique seus clientes para iterar pela matriz tasks e extrair os campos necessários.

Veja a seguir um exemplo de resposta da chamada à API Get em um trabalho de formato de várias tarefas. Este exemplo é para a 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"
}

Executa Get

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

A resposta para uma execução de trabalho de formato de várias tarefas contém uma matriz de TaskSettings. Para recuperar os resultados de cada tarefa:

  • Itere em cada uma das tarefas.
  • Analise o run_id de cada tarefa.
  • Chame a operação Obter a saída de uma execução (GET /jobs/runs/get-output) com o run_id para obter detalhes da 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"
}

Executa a saída Get

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

Para trabalhos de formato de várias tarefas, a chamada Runs get output de uma execução pai resulta em um erro, pois a saída da execução está disponível somente para tarefas individuais. Para obter a saída e os metadados de um trabalho de formato de várias tarefas:

  • Chame a solicitação Obter a saída de uma execução.
  • Itere sobre os campos filho run_id na resposta.
  • Use os valores filho run_id para chamar Runs get output.

Executa a lista

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

Para trabalhos de formato de várias tarefas, uma matriz vazia tasks é retornada. Passe o run_id para a operação Obter uma execução de trabalho (GET /jobs/runs/get) para recuperar as tarefas. Veja a seguir um exemplo de resposta da chamada à API Runs list em um trabalho de formato de várias tarefas:

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