Aktualizace z rozhraní API pro úlohy 2.0 na verzi 2.1

Teď můžete orchestrovat více úloh pomocí úloh Azure Databricks . Tento článek podrobně popisuje změny rozhraní API úloh, které podporují úlohy s více úlohami, a obsahuje pokyny, které vám pomůžou update stávající klienti rozhraní API pro práci s touto novou funkcí.

Databricks doporučuje rozhraní API úloh 2.1 pro vaše skripty a klienty rozhraní API, zejména při použití úloh s více úlohami.

Tento článek se týká úloh definovaných s jedním úkolem jako formát jednoho úkolu a úlohy definované s více úkoly jako formát více úkolů.

Rozhraní API pro pracovní úlohy 2.0 a 2.1 nyní podporuje požadavek update. Pomocí požadavku update změňte existující úlohu místo požadavku reset, abyste minimalizovali změny mezi úlohami formátu s jedním úkolem a úlohami ve formátu s více úkoly.

Změny rozhraní API

Rozhraní API úloh teď definuje objekt TaskSettings, který bude zaznamenávat nastavení pro každý úkol v úloze. Pro úlohy ve formátu více úloh je pole tasks, které obsahuje pole datových struktur TaskSettings, zahrnuto v objektu JobSettings. Některá pole, která byla dříve součástí JobSettings, jsou teď součástí nastavení úkolů pro úlohy ve formátu s více úkoly. JobSettings se také aktualizuje tak, aby zahrnovala pole format. Pole format uvádí formát úlohy a je to hodnota STRING od set do SINGLE_TASK nebo MULTI_TASK.

Pro tyto změny jobSettings musíte update stávající klienty rozhraní API pro úlohy s více úlohami formátu. Podívejte se do průvodce klienta API pro více informací o požadovaných změnách.

Rozhraní API pro úlohy 2.1 podporuje multitaskingový formát. Všechny požadavky rozhraní API 2.1 musí odpovídat tomuto formátu a odpovědi jsou strukturované v tomto formátu.

Rozhraní API úloh 2.0 se aktualizuje o další pole pro podporu úloh ve formátu více úloh. S výjimkou where uvedeno, příklady v tomto dokumentu používají rozhraní API 2.0. Databricks však doporučuje rozhraní API 2.1 pro nové a existující skripty a klienty rozhraní API.

Ukázkový dokument JSON představující úlohu ve formátu s více úlohami pro rozhraní API 2.0 a 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"
}

Rozhraní API úloh 2.1 podporuje konfiguraci clusterů na úrovni úloh nebo jednoho nebo více clusterů sdílených úloh:

• Cluster na úrovni úloh se vytvoří a spustí při spuštění a ukončení úkolu po dokončení úkolu.
• Sdílený cluster úloh umožňuje, aby více úkolů v rámci stejné úlohy využívalo cluster. Cluster je vytvořen a spuštěn při zahájení první úlohy využívající cluster a ukončen po dokončení poslední úlohy využívající cluster. Cluster sdílených úloh není ukončen při nečinnosti, ale ukončí se až po dokončení všech úkolů, které ho používají. Několik nespoléhajných úloh, které sdílejí cluster, se může spustit současně. Pokud cluster sdílených úloh selže nebo je ukončen před dokončením všech úkolů, vytvoří se nový cluster.

Ke konfiguraci clusterů sdílených úloh zahrňte do objektu JobCluster pole JobSettings. Pro úlohu můžete zadat maximálně 100 clusterů. Následuje příklad odpovědi rozhraní API 2.1 pro úlohu nakonfigurovanou se dvěma sdílenými clustery:

Poznámka

Pokud má úkol závislosti knihovny, musíte nakonfigurovat knihovny v nastavení pole task; knihovny nelze konfigurovat v konfiguraci clusteru sdílených úloh. V následujícím příkladu pole libraries v konfiguraci úlohy ingest_orders ukazuje specifikaci závislosti knihovny.

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

U úloh formátu s jedním úkolem zůstává datová struktura JobSettings beze změny s výjimkou přidání pole format. Není zahrnuto žádné pole TaskSettings a nastavení úkolů zůstává definováno na nejvyšší úrovni datové struktury JobSettings. Nebudete muset provádět žádné změny ve svých stávajících API klientech, abyste mohli zpracovávat úlohy v jednoúkolovém formátu.

Ukázkový dokument JSON pro jednoúlohový formát pro rozhraní 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"
}

Průvodce klientem rozhraní API

Tato část obsahuje pokyny, příklady a požadované změny pro volání rozhraní API ovlivněná novou funkcí formátu s více úlohami.

V této části:

• Vytvořit
• Zpracování odesílání
• Update
• Reset
• List
• Get
• spuštění get
• Spuštění get výstupu
• spuštění list

Vytvořit

Pokud chcete vytvořit práci jednoúlohového formátu prostřednictvím operace Vytvořit novou úlohu (POST /jobs/create) v API pro úlohy, nemusíte upravovat stávající klienty.

Chcete-li vytvořit úlohu formátu více úkolů, použijte pole tasks v JobSettings k určení nastavení pro každý úkol. Následující příklad vytvoří úlohu se dvěma úkoly poznámkového bloku. Tento příklad je určený pro rozhraní API 2.0 a 2.1:

Poznámka

Pro každou úlohu je možné zadat maximálně 100 úkolů.

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

Spuštění odesláno

Pokud chcete odeslat jednorázové spuštění úlohy ve formátu s jedním úkolem pomocí operace Vytvořit a aktivovat jednorázové spuštění (POST /runs/submit) v rozhraní Jobs API, nemusíte měnit stávající klienty.

Pokud chcete odeslat jednorázově spuštěnou úlohu ve formátu více úloh, použijte pole tasks v JobSettings k určení nastavení pro jednotlivé úlohy, včetně clusterů. Clustery musí být na úrovni úlohy set při odesílání úlohy s více úkoly, protože požadavek runs submit nepodporuje sdílené clustery úloh. Viz Vytvoření pro příklad JobSettings specifikující více úkolů.

Update

Pokud chcete update úlohu formátu s jedním úkolem pomocí Částečně update operace úlohy (POST /jobs/update) v rozhraní API úloh, nemusíte měnit stávající klienty.

Pokud chcete update nastavení úlohy s více úlohami ve formátu úloh, musíte k identifikaci nových nastavení task použít jedinečné pole task_key. Viz Vytvoření pro příklad JobSettings specifikující více úkolů.

Reset

Pokud chcete přepsat nastavení jednoúkolové úlohy pomocí Přepsat všechna nastavení úlohy operace (POST /jobs/reset) v API pro úlohy, nemusíte měnit stávající klienty.

Chcete-li přepsat nastavení úlohy formátu pro více úloh, zadejte datovou strukturu JobSettings s polem datových struktur TaskSettings. Viz Vytvoření pro příklad JobSettings specifikující více úkolů.

Pomocí Update můžete změnit jednotlivá pole bez přechodu z jednoho úkolu na formát více úkolů.

List

U úloh s jedním úkolem nejsou vyžadovány žádné změny klienta pro zpracování odpovědi z operace List všechny úlohy (GET /jobs/list) v rozhraní API úloh.

U úloh ve formátu s více úlohami se většina nastavení definuje na úrovni úkolu, nikoli na úrovni úlohy. Konfigurace clusteru může být set na úrovni úkolu nebo úlohy. K úpravě klientů pro přístup k nastavení clusteru nebo úlohy pro formát více úloh vrácených ve struktuře Job:

• Analyzujte pole job_id pro úlohu formátu souběžných úloh.
• Předejte job_id do Get operace úlohy (GET /jobs/get) v rozhraní API úloh pro načtení podrobností úlohy. Podívejte se na Get pro příklad odpovědi z volání rozhraní API Get pro úlohu s formátem pro více úloh.

Následující příklad ukazuje odpověď obsahující úlohy ve formátu jednoúkolovém a víceúkolovém. Tento příklad je určený pro rozhraní 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"
    }
  ]
}

Get

U úloh s formátem na jednorázový úkol nejsou potřeba žádné změny klienta ke zpracování odpovědi z operace Get pro úlohu (GET /jobs/get) v rozhraní API systému úloh.

Úlohy ve formátu více úloh vracejí pole datových struktur typu task obsahujících nastavení úkolů. Pokud potřebujete přístup k podrobnostem na úrovni úlohy, musíte upravit klienty, aby iterovali prostřednictvím pole tasks a extrahovali požadovaná pole.

Následující příklad ukazuje odpověď z volání rozhraní API Get pro úlohu ve formátu s více úlohami. Tento příklad je určený pro rozhraní API 2.0 a 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"
}

spuštění get

U úloh s jedním úkolem nejsou potřeba žádné změny klienta ke zpracování odpovědi ze spuštění úlohy operací Get (GET /jobs/runs/get) v API pro úlohy.

Odpověď pro spuštění úlohy ve formátu multi-taskingu obsahuje pole TaskSettings. Chcete-li načíst výsledky spuštění pro jednotlivé úlohy, postupujte takto:

• Iterujte jednotlivé úkoly.
• Parsujte run_id pro každý úkol.
• Zavolejte výstup Get pro operaci spuštění (GET /jobs/runs/get-output) s podrobnostmi od run_id do get o spuštění jednotlivých úloh. Následuje příklad odpovědi z tohoto požadavku:

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

spuštění get výstup

U úloh ve formátu jednoho úkolu nejsou k zpracování odpovědi z Get výstupu operace spuštění (GET /jobs/runs/get-output) v rozhraní API úloh potřeba žádné změny klienta.

U úloh ve formátu s více úlohami má volání Runs get output na nadřazený proces za následek chybu, protože výstup spuštění je k dispozici pouze pro jednotlivé úlohy. Pokud chcete get výstup a metadata pro úlohu ve formátu více úloh:

• Zavolejte výstup Get pro požadavek na spuštění.
• Iterujte pole podřízeného run_id v odpovědi.
• K volání Runs get outputpoužijte dítě run_idvalues.

spuštění list

U úloh v formátu s jedním úkolem nejsou vyžadovány žádné změny na straně klienta pro zpracování odpovědi ze spuštění List pro operaci úlohy (GET /jobs/runs/list).

U úloh ve formátu více úloh se vrátí prázdné pole tasks. Předat run_id v rámci operace spuštění úlohy Get (GET /jobs/runs/get) pro načtení úkolů. Následuje příklad odpovědi z volání rozhraní API Runs list pro úlohu ve formátu s více úlohami:

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