Atualização da API de trabalhos 2.0 para 2.1

Agora pode orquestrar múltiplas tarefas com o Azure Databricks jobs. Este artigo detalha as alterações na API de Trabalhos , que suportam trabalhos com múltiplas tarefas, e fornece orientações para ajudá-lo a atualizar os seus clientes de API existentes para funcionar com esta nova funcionalidade.

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 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 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 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 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 onde indicado, 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 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
• Submissões em execução
• Atualização
• Redefinir
• Lista
• Obtenha
• Obtenha runs
• Execuções geram saída
• Lista de execuções

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 definidos no nível da tarefa ao enviar um trabalho de 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.

Atualização

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

Para atualizar as configurações de uma tarefa de formato multitarefa, deve-se usar o campo task_key exclusivo para identificar novas configurações task. Consulte Criar para ver um exemplo JobSettings que especifica várias tarefas.

Redefinir

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 a atualização para alterar campos individuais sem alternar do formato de tarefa única para tarefa múltipla.

Lista

Para trabalhos de formato de tarefa única, nenhuma alteração de cliente é necessária para processar a resposta do Listar 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 definida 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 Obter um emprego (GET /jobs/get) na API de empregos para recuperar detalhes do emprego. Veja e Obtenha para um exemplo de resposta da chamada de API do Get para um trabalho em formato de tarefa múltipla.

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

Obter

Para tarefas de formato único, não são necessárias alterações no cliente para processar a resposta da função Obter um Trabalho (GET /jobs/get) 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"
}

Execuções obtêm

Para trabalhos de formato de tarefa única, nenhuma alteração de cliente é necessária para processar a resposta do executar um trabalho operação (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 para obter a saída de uma operação de execução (GET /jobs/runs/get-output) com o run_id, para conseguir detalhes sobre a execução de 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"
}

As execuções produzem saída

Para trabalhos de formato de tarefa única, não são necessárias alterações do cliente para processar a resposta da operação Obter a saída para uma 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 obter a saída e os metadados para uma tarefa em formato multitarefa:

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

Lista de execuções

Para trabalhos de formato de tarefa única, nenhuma alteração de cliente é necessária para processar a resposta da lista de executada para uma operação de de trabalho (GET /jobs/runs/list).

Para tarefas em formato multitarefa, retorna-se um array vazio de tasks. Passe o run_id para o e execute a operação (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
}