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 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 úloh 2.0 a 2.1 teď podporuje požadavek na 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 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 nastaveno na hodnotu STRING nebo SINGLE_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.

V této části:

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 ve formátu více úloh, protože runs submit požadavek nepodporuje clustery sdílených úloh. Viz Vytvoření pro příklad JobSettings specifikují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í víceúlohové formátové úlohy, musíte použít jedinečné task_key pole k identifikaci nových task nastavení. Viz Vytvoření pro příklad JobSettings specifikující více úkolů.

Resetovat

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í 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 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.
  • job_id Předejte operaci 'Získat úlohu' (GET /jobs/get) v rozhraní API pro úlohy a načtěte podrobnosti úlohy. Viz Získání příkladné odpovědi z volání Get API pro vícenásobný formát úlohy.

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

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

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 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 operaci získat výstup pro spuštění pomocí GET /jobs/runs/get-output, abyste získali podrobnosti o běhu pro každý úkol. 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 pro zpracování odpovědi z operace Získat výstup pro spuštění (GET /jobs/runs/get-output) v rozhraní API úloh vyžadovány žádné změny na straně 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:

  • Zavolejte požadavek Získejte výstup pro spuštění.
  • Iterujte pole podřízeného run_id v odpovědi.
  • K volání run_id použijte hodnoty dítěte Runs get output.

Seznam běhů

U úloh ve formátu jednoho úkolu nejsou nutné žádné změny na straně klienta pro zpracování odpovědi z operace List runs for a job (GET /jobs/runs/list).

U úloh ve formátu více úloh se vrátí prázdné pole tasks. run_id Předávejte operaci Získat běh úlohy (GET /jobs/runs/get) k načtení úloh. 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
}
  • Last updated on