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 contém orientações 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 são compatíveis com 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, está incluído no objeto JobSettings. Alguns campos que antes faziam parte do site JobSettings agora fazem parte das configurações de tarefa para o trabalho em formato 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 da API 2.1 devem estar em conformidade com esse formato, e as respostas são estruturadas nesse formato.
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 oferece suporte à configuração de clustering no nível da tarefa ou de um ou mais clustering de trabalhos compartilhados:
Um clustering no nível da tarefa é criado e começa quando uma tarefa começa e termina quando a tarefa é concluída.
Um clustering de trabalho compartilhado permite que várias tarefas no mesmo trabalho usem o clustering. O clustering é criado e começa quando a primeira tarefa que usa o clustering começa e termina após a conclusão da última tarefa que usa o clustering. Um clustering de trabalho compartilhado não é encerrado quando parado, mas é encerrado somente depois que todas as tarefas que o utilizam são concluídas. Várias tarefas não dependentes de compartilhamento de um clustering podem começar ao mesmo tempo. Se um clustering de trabalho compartilhado falhar ou for encerrado antes que todas as tarefas tenham sido concluídas, um novo clustering será criado.
Para configurar o clustering de trabalho compartilhado, inclua uma matriz JobCluster no objeto JobSettings. O senhor pode especificar um máximo de 100 clusters por Job. A seguir, um exemplo de resposta do 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 configurações do campo task; a biblioteca não pode ser configurada em uma configuração de clustering 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 o Job de formato de tara ú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 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 para 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 Job de formato multitarefa, use o campo tasks em JobSettings para especificar as configurações de cada tarefa, incluindo o clustering. o clustering deve ser definido no nível da tarefa ao enviar um trabalho de formato multitarefa porque a solicitação runs submit não oferece suporte ao clustering de trabalhos compartilhados. Consulte Create para ver um exemplo JobSettings especificando 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 Create para ver um exemplo JobSettings especificando 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 Create para ver um exemplo JobSettings especificando 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 de clustering pode ser definida no nível da tarefa ou do trabalho. Para modificar os clientes para acessar as configurações de clustering ou tarefa para um Job de formato multitarefa retornado na estrutura Job:
Analisar o campo
job_idpara o Job 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 obter 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 tarefa ú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 multi-tarefa 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 necessá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 em 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 site
run_idpara cada tarefa.Chame a opção Get the output for a execução operações (
GET /jobs/runs/get-output) com o endereçorun_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
No caso de um trabalho de formato de tara única, não são necessárias alterações no cliente para processar a resposta da opção Get the output for a execução 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 somente 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 do Job 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 JobGET /jobs/runs/list().
Para o Job de formato multitarefa, é retornado um array tasks vazio. Passe run_id o endereço para o Get a Job operações de execuçãoGET /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
}