Sdílet prostřednictvím

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

  • Článek

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 poskytuje 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 úloh definovaných s více úkoly ve formátu více úkolů.

Rozhraní API úloh 2.0 a 2.1 teď podporuje žádost o aktualizaci . update Pomocí požadavku můžete místo žádosti o resetování změnit existující úlohu, abyste minimalizovali změny mezi úlohami formátu s jedním úkolem a úlohami ve formátu s více úlohami.

Změny rozhraní API

Rozhraní API úloh teď definuje TaskSettings objekt, který bude zaznamenávat nastavení pro každý úkol v úloze. V případě úloh tasks s více úlohami formátu je pole pole datových TaskSettings struktur součástí objektu JobSettings . Některá pole, která JobSettings byla dříve součástí, jsou teď součástí nastavení úkolů pro úlohy ve formátu s více úkoly. JobSettings aktualizuje se také tak, aby zahrnovalo format pole. Pole format označuje formát úlohy a je hodnota nastavená STRING na SINGLE_TASK hodnotu 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. Další informace o požadovaných změnách najdete v průvodci klientem rozhraní API.

Rozhraní API úloh 2.1 podporuje formát s více úlohami. Všechny požadavky rozhraní API 2.1 musí odpovídat formátu více úloh a odpovědi jsou strukturované ve formátu s více úlohami. Nové funkce jsou vydány pro rozhraní API 2.1 jako první.

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.
  • Cluster sdílených úloh umožňuje použití clusteru více úloh ve stejné úloze. Cluster se vytvoří a spustí při prvním spuštění úlohy, která cluster spustí a ukončí po dokončení poslední úlohy pomocí clusteru. 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.

Pokud chcete nakonfigurovat clustery sdílených úloh, zahrňte JobCluster do objektu JobSettings pole. 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á úloha závislosti knihovny, musíte nakonfigurovat knihovny v task nastavení polí. Knihovny nelze konfigurovat v konfiguraci clusteru sdílených úloh. V následujícím příkladu libraries pole v konfiguraci ingest_orders úlohy 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 JobSettings formátu s jedním úkolem zůstává datová struktura beze změny s výjimkou přidání format pole. Není zahrnuto žádné TaskSettings pole a nastavení úkolů zůstává definováno na nejvyšší úrovni JobSettings datové struktury. Abyste mohli zpracovávat úlohy formátu s jedním úkolem, nebudete muset stávající klienti rozhraní API provádět změny.

Ukázkový dokument JSON představující úlohu formátu s jedním úkolem 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:

Vytvářet

Pokud chcete vytvořit úlohu formátu s jedním úkolem prostřednictvím operace Vytvořit novou úlohu (POST /jobs/create) v rozhraní API úloh, nemusíte měnit stávající klienty.

Pokud chcete vytvořit úlohu ve formátu více úkolů, zadejte nastavení pro každý úkol pomocí tasks pole JobSettings . 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í odesílané

Pokud chcete odeslat jednorázově spuštěnou úlohu s jedním úkolem s úlohou Vytvořit a aktivovat jednorázovou operaci běhu (POST /runs/submit) v rozhraní API úloh, nemusíte měnit stávající klienty.

Pokud chcete odeslat jednorázový běh úlohy s více úlohami ve formátu úloh, použijte tasks pole JobSettings k určení nastavení pro každou úlohu, včetně clusterů. Clustery musí být nastaveny na úrovni úlohy při odesílání úlohy ve formátu více úloh, protože runs submit požadavek nepodporuje clustery sdílených úloh. Viz Vytvoření příkladu JobSettings určující více úkolů.

Aktualizace

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

Chcete-li aktualizovat nastavení úlohy s více úkoly ve formátu, musíte použít jedinečné task_key pole k identifikaci nových task nastavení. Viz Vytvoření příkladu JobSettings určující více úkolů.

Resetovat

Pokud chcete přepsat nastavení úlohy s jedním úkolem pomocí přepsání všech nastavení operace úlohy (POST /jobs/reset) v rozhraní API úloh, nemusíte měnit stávající klienty.

Chcete-li přepsat nastavení úlohy formátu s více úlohami úkolů, zadejte datovou JobSettings strukturu s polem datových TaskSettings struktur. Viz Vytvoření příkladu JobSettings určující více úkolů.

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

Seznam

U úloh ve formátu jednoho úkolu nejsou k zpracování odpovědi ze seznamu všech úlohGET /jobs/list v rozhraní API úloh vyžadovány žádné změny klienta.

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 úlohy nebo úlohy. Úprava klientů pro přístup k nastavení clusteru nebo úlohy pro úlohu ve více úlohách vrácených ve struktuře Job :

  • Parsujte job_id pole pro úlohu ve formátu s více úkoly.
  • job_id Předejte operaci Získání úlohy (GET /jobs/get) v rozhraní API úloh a načtěte podrobnosti úlohy. Viz Získání ukázkové odpovědi z Get volání rozhraní API pro úlohu s více úlohami formátu.

Následující příklad ukazuje odpověď obsahující úlohy s jedním úkolem a více úlohami formátu. 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"
    }
  ]
}

Dostat

U úloh ve formátu jednoho úkolu nejsou k zpracování odpovědi z operace Získání úlohy (GET /jobs/get) v rozhraní API úloh vyžadovány žádné změny klienta.

Úlohy formátu s více úlohami vrátí pole datových task struktur obsahujících nastavení úkolů. Pokud potřebujete přístup k podrobnostem na úrovni úlohy, musíte upravit klienty tak, aby iterovat pole tasks a extrahovali požadovaná pole.

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

Získání spuštění

U úloh ve formátu jednoho úkolu nejsou k zpracování odpovědi z operace Get a job run (GET /jobs/runs/get) v rozhraní API úloh vyžadovány žádné změny klienta.

Odpověď pro spuštění úlohy s více úlohami ve formátu obsahuje pole TaskSettings. Načtení výsledků spuštění pro jednotlivé úlohy:

  • Iterujte jednotlivé úkoly.
  • Parsujte run_id pro každý úkol.
  • Zavolejte get the output for a run operation (GET /jobs/runs/get-output) with the run_id get details on the run run for each task. 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í – získání výstupu

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

U úloh ve formátu více úloh má volání Runs get output nadřazeného spuštění 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:

  • Volání výstupu get for a run request.
  • Iterujte podřízená run_id pole v odpovědi.
  • K volání Runs get outputpoužijte podřízené run_id hodnoty .

Seznam spuštění

U úloh ve formátu jednoho úkolu nejsou k zpracování odpovědi ze seznamu pro operaci úlohy (GET /jobs/runs/list) potřeba žádné změny klienta.

U úloh ve formátu více úloh se vrátí prázdné tasks pole. run_id Předejte operaci get a job run (GET /jobs/runs/get) to retrieve the tasks. Následující příklad odpovědi z Runs list volání rozhraní API 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
}