Partilhar via

Atualização da API de trabalhos 2.0 para 2.1

  • Artigo

Agora você pode orquestrar várias tarefas com trabalhos do Azure Databricks. Este artigo detalha as alterações na API de trabalhos que suportam trabalhos com várias tarefas e fornece 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.

As APIs de trabalhos 2.0 e 2.1 agora suportam a solicitação de atualização . Use a update solicitação 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 da API

A API de Trabalhos agora define um objeto para capturar configurações para cada tarefa em um TaskSettings trabalho. Para trabalhos de formato multitarefa, o tasks campo, uma matriz de estruturas de TaskSettings dados, é incluído no JobSettings objeto. Alguns campos que anteriormente faziam parte JobSettings agora fazem parte das configurações de tarefas para trabalhos de formato multitarefa. 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 em JobSettings para trabalhos de formato multitarefa. Consulte o guia do cliente de 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 o formato multitarefa e as respostas são estruturadas no formato multitarefa. Novos recursos são lançados para a API 2.1 primeiro.

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 tarefas compartilhadas 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 JobCluster matriz no JobSettings objeto. 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:

Nota

Se uma tarefa tiver dependências de biblioteca, você deverá configurá-las nas configurações de task campo; as bibliotecas não podem ser configuradas em uma configuração de cluster de trabalho compartilhado. No exemplo a seguir, o libraries campo na configuração da tarefa demonstra a ingest_orders 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 permanece inalterada, exceto para a JobSettings adição do format campo. Nenhuma TaskSettings matriz é incluída e as configurações da 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 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 formato 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 tasks campo in 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:

Nota

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ção enviar

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

Para enviar uma execução única de um trabalho de formato multitarefa, use o tasks campo in 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 não oferece suporte a runs submit clusters de trabalho compartilhados. Consulte Criar para obter um exemplo JobSettings especificando várias tarefas.

Atualizar

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 um trabalho de formato multitarefa, você deve usar o campo exclusivo task_key para identificar novas task configurações. Consulte Criar para obter um exemplo JobSettings especificando várias tarefas.

Repor

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

Para substituir as configurações de um trabalho de formato multitarefa, especifique uma estrutura de dados com uma JobSettings matriz de estruturas de TaskSettings dados. 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 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 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 acessar configurações de cluster ou tarefa para um trabalho de formato multitarefa retornado na Job estrutura:

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 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.

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

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

Corridas obter

Para trabalhos de formato de tarefa única, nenhuma alteração de 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 multitarefa contém uma matriz de TaskSettings. Para recuperar resultados de execução para cada tarefa:

{
  "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 obtêm saída

Para trabalhos de formato de tarefa única, nenhuma alteração de cliente é necessária 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 formato multitarefa, chamar Runs get output uma execução pai resulta em um erro, uma vez que a saída de execução está disponível apenas para tarefas individuais. Para obter a saída e os metadados para um trabalho de formato multitarefa:

Lista de execuções

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

Para trabalhos de formato multitarefa, 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. A seguir mostra um exemplo de resposta da Runs list chamada de API 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
}