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

Článek
01/22/2025

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 aktualizovat stávající klienty rozhraní API tak, aby fungovaly 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 úlohy verze 2.0 a 2.1 nyní podporují požadavek na aktualizaci . Použijte požadavek update ke změně existující úlohy místo požadavku na reset , abyste minimalizovali změny mezi úlohami s jedním úkolem a úlohami 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 označuje formát úlohy a je hodnota STRING nastavená na SINGLE_TASK nebo MULTI_TASK.

Pro tyto změny jobSettings je potřeba aktualizovat stávající klienty rozhraní API pro úlohy ve formátu s více úlohami. 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. Pokud není 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.

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 nastaveny na úrovni úlohy při odesílání úlohy s více úlohami, protože požadavek runs submit nepodporuje clustery sdílených úloh. Viz Vytvoření pro příklad JobSettings specifikující více úkolů.

aktualizace

Pokud chcete aktualizovat úlohu v formátu s jedním úkolem pomocí operace Částečné aktualizace úlohy (POST /jobs/update) v API pro úlohy, nemusíte upravovat stávající klienty.

Chcete-li aktualizovat nastavení úlohy ve formátu více úloh, je nutné použít jedinečné pole task_key k identifikaci nových nastavení task. Viz Vytvoření pro příklad JobSettings specifikující více úkolů.

resetování

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 s více úlohami.

seznam

U úloh formátu s jedním úkolem nejsou k zpracování odpovědi z v rozhraní API úloh vyžadovány žádné změny úloh (GET /jobs/list).

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 nastavena na úrovni úkolu nebo práce. 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 operace Získání úlohy v rozhraní Jobs API pro získání podrobností úlohy (GET /jobs/get). Podívejte se na Získejte pro příklad odpovědi z volání Get API pro formát úlohy s více úkoly.

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

získat

U úloh ve formátu s jedním úkolem nejsou potřeba žádné změny klienta ke zpracování odpovědi z Získání operace úlohy (GET /jobs/get) v rozhraní API ú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"
}

Provozy se spouštějí

U úloh v jednoúlohovém formátu nejsou nutné žádné změny na straně klienta pro zpracování odpovědi z operace spuštění úlohy (GET /jobs/runs/get) v rozhraní Jobs API.

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.
Proveďte příkaz pro získání výstupu z operace běhu (GET /jobs/runs/get-output) s pomocí run_id, abyste dostali podrobnosti o běhu každého úkolu. 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"
}

získání výstupu spuštění

U úloh formátu s jedním úkolem nejsou k zpracování odpovědi z získání 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. Získání výstupu a metadat pro úlohu ve formátu s více úlohami:

Volejte pro získání výstupu ze spuštění požadavku.
Iterujte pole podřízeného run_id v odpovědi.
K volání run_idpoužijte podřízené hodnoty Runs get output.

Seznam běhů

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

U úloh ve formátu více úloh se vrátí prázdné pole tasks. Předejte run_id do pro spuštění operace načítání úloh (GET /jobs/runs/get) a získání ú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
}

Sdílet prostřednictvím