Amazon
Web Services
Microsoft Azure
Google Cloud PlatformAtualização da API do Jobs 2.0 para a 2.1
Agora o senhor pode orquestrar várias tarefas com o Databricks Job. Este artigo detalha as alterações no Jobs API que suportam o Job com várias tarefas e fornece orientação para ajudá-lo a atualizar seus clientes API existentes para trabalhar com esse novo recurso.
Databricks recomenda o site Jobs API 2.1 para seus scripts e clientes API, especialmente ao usar o Job com várias tarefas.
Este artigo se refere ao trabalho definido com uma única tarefa como formato de tarefa única e ao trabalho definido com várias tarefas como formato de várias tarefas.
Os trabalhos API 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 Reset para minimizar as alterações entre um trabalho de formato de tara única e um trabalho de formato de tara múltipla.
Alterações na API
O site Jobs API agora define um objeto TaskSettings para capturar as configurações de cada tarefa em um Job. No caso do Job de formato multitarefa, o campo tasks, uma matriz de estruturas de dados TaskSettings, é incluído no objeto JobSettings. Alguns campos que antes faziam parte de JobSettings agora fazem parte das configurações de tarefa para o formato de tarefa multitarefa. 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.
O senhor precisa atualizar os clientes existentes do site API para essas alterações no JobSettings para o trabalho de formato multitarefa. Consulte o guia do clienteAPI para obter mais informações sobre as alterações necessárias.
O Jobs API 2.1 é compatível com o formato multitarefa. Todas as solicitações do API 2.1 devem estar em conformidade com o formato multi-tarefa e as respostas são estruturadas no formato multi-tarefa. Os novos recursos são lançados primeiro para API 2.1.
O site Jobs API 2.0 foi atualizado com um campo adicional para oferecer suporte a trabalhos em formato multitarefa. Exceto quando indicado, os exemplos deste documento usam a API 2.0. No entanto, a 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"
}
O Jobs API 2.1 suporta a configuração do nível de tarefa clusters ou um ou mais Jobs clusters compartilhados:
Um nível de tarefa cluster é criado e começa quando uma tarefa começa e termina quando a tarefa é concluída.
Um trabalho compartilhado cluster permite que várias tarefas no mesmo trabalho usem o cluster. O cluster é criado e começa quando a primeira tarefa usando o cluster começa e termina após a conclusão da última tarefa usando o cluster. Um trabalho compartilhado cluster não é encerrado quando parado, mas é encerrado somente depois que todas as tarefas que o utilizam são concluídas. Múltiplas tarefas não dependentes de compartilhamento a cluster podem começar ao mesmo tempo. Se um trabalho compartilhado cluster falhar ou for encerrado antes que todas as tarefas tenham sido concluídas, um novo cluster será criado.
Para configurar o trabalho compartilhado clusters, inclua uma matriz JobCluster no objeto JobSettings. O senhor pode especificar um máximo de 100 clusters por trabalho. A seguir, um exemplo de uma resposta API 2.1 para um trabalho configurado com dois clusters compartilhados:
Observação
Se uma tarefa tiver dependências de biblioteca, o senhor deverá configurar a biblioteca nas definições do campo task; a biblioteca não pode ser configurada em uma configuração compartilhada do Job cluster. 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 o formato Job de tara única, a estrutura de dados JobSettings permanece inalterada, exceto pela adição do campo format. Nenhuma matriz TaskSettings é incluída, e as configurações da tarefa permanecem definidas no nível superior da estrutura de dados JobSettings. O senhor não precisará fazer alterações nos clientes existentes do site API para processar o Job de formato de tara única.
Um exemplo de documento JSON que representa um trabalho de formato de tara única para 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"
}
API guia do cliente
Esta seção fornece diretrizes, exemplos e alterações necessárias para as chamadas do site API afetadas pelo novo recurso de formato multitarefa.
Nesta secção:
Criar
Para criar um trabalho de formato de tara única por meio da operação Create a new Job (POST /jobs/create) no site Jobs API, o senhor não precisa alterar os clientes existentes.
Para criar um trabalho de formato multitarefa, use o campo tasks em JobSettings para especificar as configurações de cada tarefa. O exemplo a seguir cria um Job com duas tarefas de Notebook. Este exemplo é para API 2.0 e 2.1:
Observação
É possível especificar um máximo de 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
}
]
}
execução submit
Para enviar uma execução única de um trabalho de formato de tara única com a opção Criar e acionar uma execução única de operações (POST /runs/submit) em Jobs API, o senhor não precisa alterar os clientes existentes.
Para enviar uma execução única de um trabalho de formato multitarefa, use o campo tasks em JobSettings para especificar as configurações de cada tarefa, inclusive clusters. Os clusters devem ser definidos no nível da tarefa ao enviar um trabalho de formato multitarefa porque a solicitação runs submit não oferece suporte a trabalhos compartilhados clusters. Consulte Criar para ver um exemplo JobSettings de especificação de várias tarefas.
Atualizar
Para atualizar um trabalho de formato de tara única com a opção Partially update a Job operações (POST /jobs/update) em Jobs API, não é necessário alterar os clientes existentes.
Para atualizar as configurações de um Job de formato multitarefa, o senhor deve usar o campo exclusivo task_key para identificar as novas configurações task. Consulte Criar para ver um exemplo JobSettings de especificação de várias tarefas.
Reset
Para sobrescrever as configurações de um trabalho de formato de tara única com a opção Overwrite all settings for a Job operações (POST /jobs/reset) em Jobs API, não é necessário alterar os clientes existentes.
Para substituir as configurações de um Job de formato multitarefa, especifique uma estrutura de dados JobSettings com uma matriz de estruturas de dados TaskSettings. Consulte Criar para ver um exemplo JobSettings de especificação de várias tarefas.
Use o Update para alterar campos individuais sem mudar do formato de tara única para o formato de tara múltipla.
Lista
No caso do Job em formato de tarefa única, não são necessárias alterações no cliente para processar a resposta da opção List all Job operações (GET /jobs/list) em Jobs API.
No caso do trabalho de formato multitarefa, 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 os clientes para acessar cluster ou as configurações de tarefa para um trabalho de formato multitarefa retornado na estrutura Job:
Analisar o campo
job_idpara o trabalho de formato multitarefa.Passe o
job_idpara a operação Get a Job (GET /jobs/get) no site Jobs API para obter detalhes do trabalho. Consulte Get para ver um exemplo de resposta da chamadaGetAPI para um Job de formato multitarefa.
O exemplo a seguir mostra uma resposta que contém um Job de formato de tara única e de tara múltipla. 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 o Job de formato de tara única, não são necessárias alterações no cliente para processar a resposta das operações Get a Job (GET /jobs/get) em Jobs API.
Formato multitarefa O trabalho retorna uma matriz de estruturas de dados task contendo configurações de tarefa. Se o senhor precisar acessar os detalhes do nível da tarefa, precisará modificar seus clientes para iterar pela matriz tasks e extrair os campos obrigatórios.
A seguir, um exemplo de resposta da chamada Get API para um Job 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ção get
No caso de um trabalho de formato de tara única, não são necessárias alterações no cliente para processar a resposta das operações de execução do Get a Job (GET /jobs/runs/get) no site Jobs API.
A resposta para a execução de um trabalho no formato multitarefa contém uma matriz de TaskSettings. Para recuperar os resultados da execução de cada tarefa:
Iterar por cada uma das tarefas.
Analisar o
run_idpara cada tarefa.Chame a opção Obter a saída para uma execução de operações (
GET /jobs/runs/get-output) comrun_idpara obter detalhes sobre a execução de cada tarefa. Veja a seguir um exemplo de resposta dessa 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ção get output
Para o trabalho de formato de tarefa única, não são necessárias alterações no cliente para processar a resposta da opção Obter a saída para uma execução de operações (GET /jobs/runs/get-output) no site Jobs API.
No caso do Job de formato multitarefa, chamar Runs get output em uma execução pai resulta em um erro, pois a saída da execução está disponível apenas para tarefas individuais. Para obter a saída e os metadados de um trabalho em formato multitarefa:
Chame a função Obter a saída de uma solicitação de execução.
Repita sobre os campos child
run_idna resposta.Use os valores do filho
run_idpara chamarRuns get output.
lista de execução
No caso de um trabalho de formato de tarefa única, não são necessárias alterações no cliente para processar a resposta da execução da lista de operações de um trabalhoGET /jobs/runs/list().
Para o Job de formato multitarefa, é retornado um array tasks vazio. Passe o run_id para a operação de execução Get a Job (GET /jobs/runs/get) para recuperar a tarefa. A seguir, um exemplo de resposta da chamada Runs list API para um Job 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
}