Compartilhar via

Atualização da API de Trabalhos 2.0 para 2.1

Agora você pode orquestrar várias tarefas com trabalhos do Azure Databricks. Este artigo detalha as alterações na API de Trabalhos que dão suporte a trabalhos com várias tarefas e tem orientação para ajudá-lo a atualizar seus clientes de API existentes 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.

Jobs API 2.0 e 2.1 agora dão suporte à solicitação de atualização. Use a solicitação update para alterar um trabalho existente 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

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

Você precisa atualizar seus clientes de API existentes para essas alterações no JobSettings para tarefas no formato de múltiplas tarefas. Consulte o guia do cliente da API para obter mais informações sobre as alterações necessárias.

A Jobs API 2.1 dá suporte ao formato multitarefas. 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 Empregos 2.0 é atualizada com um campo adicional para dar suporte a trabalhos em formato multitarefa. Exceto quando observado, os exemplos neste documento usam a API 2.0. No entanto, o Databricks recomenda a API 2.1 para scripts e clientes de API novos e existentes.

Um documento JSON de exemplo que representa uma tarefa em formato multitarefa 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 um ou mais clusters de trabalho 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 no mesmo trabalho usem o cluster. O cluster é criado e iniciado quando a primeira tarefa usando o cluster é iniciada e termina após a última tarefa usando o cluster ser concluída. 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 trabalho compartilhado falhar ou for encerrado antes de todas as tarefas serem concluídas, um novo cluster será criado.

Para configurar clusters de trabalho compartilhado, inclua uma JobCluster matriz no JobSettings objeto. Você pode especificar um máximo de 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 tiver dependências de biblioteca, você deverá definir as bibliotecas nas configurações de campo; as task bibliotecas não poderão 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 JobSettings estrutura de dados permanece inalterada, exceto pela adição do format campo. Nenhuma TaskSettings matriz está incluída e as configurações de tarefa permanecem definidas no nível superior da JobSettings estrutura de dados. Você não precisará fazer alterações em seus clientes de API existentes para processar trabalhos de formato de tarefa única.

Um documento JSON de exemplo que representa uma tarefa de formato único 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 à API afetadas pelo novo recurso de formato de várias tarefas.

Nesta seção:

Criar

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

Para criar uma tarefa no formato multitarefas, use o campo JobSettings em tasks para especificar os parâmetros 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

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

Execuções de envio

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

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

Atualização

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

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

Reset

Para substituir as configurações de um trabalho em formato de tarefa única com a operação Substituir todas as configurações de um trabalho na API de Trabalhos, não é necessário alterar os clientes existentes.

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

Use Atualizar para alterar campos individuais sem mudar de formato de tarefa única para formato multitasca.

Lista

Para trabalhos de formato de tarefa única, nenhuma alteração de 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 a fim de acessar as configurações de cluster ou de tarefa para uma tarefa de formato múltiplo retornada na estrutura Job:

  • Analise o campo job_id para o trabalho de formato multitarefa.
  • Passe o job_id para a operação Obter emprego (GET /jobs/get) na API de Vagas para recuperar detalhes do emprego. Consulte Get para uma resposta de exemplo da chamada à Get API para um trabalho de formato de tarefas múltiplas.

O exemplo a seguir mostra uma resposta que contém trabalhos de formato de tarefa única e 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 de cliente é necessária para processar a resposta da operação Obter um trabalho (GET /jobs/get) na API de Trabalhos.

Trabalhos em formato multitarefa retornam um array de estruturas de task dados que contêm configurações de tarefa. Se você precisar de acesso aos detalhes no nível de tarefa, será necessário modificar seus clientes de software para iterar por meio da matriz tasks e extrair os campos necessários.

O exemplo a seguir mostra uma resposta de exemplo da chamada à Get API para 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"
}

Execuções

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

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

  • Percorrer 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 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ções de processos produzem saída

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

Para trabalhos com formato de múltiplas tarefas, chamar Runs get output em uma execução pai resulta em um erro, pois os resultados da execução estão disponíveis apenas para tarefas individuais. Para obter a saída e os metadados de um trabalho de formato de várias tarefas:

  • Realize a chamada para a solicitação Obtenha a saída de uma execução.
  • Iterar sobre os campos filho run_id na resposta.
  • Use os valores filho run_id para chamar Runs get output.

Lista de execuções

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

Para formatos de trabalhos com várias tarefas, uma matriz vazia tasks é retornada. Passe o run_id para a operação Obter execução de trabalho (GET /jobs/runs/get) para recuperar as tarefas. O seguinte é um exemplo de resposta da chamada à API Runs list para um trabalho com 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
}
  • Last updated on