Aktualisieren von Auftrags-API 2.0 auf 2.1
Sie können jetzt mehrerer Aufgaben mit Azure Databricks-Aufträgen orchestrieren. Dieser Artikel beschreibt die Änderungen an der Auftrags-API, die Aufträge mit mehreren Aufgaben unterstützen. Außerdem erhalten Sie eine Anleitung, wie Sie Ihre bestehenden API-Clients aktualisieren können, um mit dieser neuen Funktion zu arbeiten.
Databricks empfiehlt die Auftrags-API 2.1 für Ihre API-Skripts und -Clients, insbesondere bei der Verwendung von Aufträgen mit mehreren Aufgaben.
Dieser Artikel bezieht sich auf Aufträge, die mit einer einzelnen Aufgabe als Einzeltaskformat definiert sind, sowie auf Aufträge, die mit mehreren Aufgaben als Multitaskformat definiert sind.
Die Auftrags-APIs 2.0 und 2.1 unterstützen jetzt die Update-Anforderung. Verwenden Sie zum Ändern eines vorhandenen Auftrags die update-Anforderung anstelle der reset-Anforderung (Zurücksetzen), um Änderungen zwischen Aufträgen im Einzeltaskformat und Aufträgen im Multitaskformat zu minimieren.
API-Änderungen
Die Auftrags-API definiert nun ein TaskSettings-Objekt, um Einstellungen für jede Aufgabe in einem Auftrag zu erfassen. Bei Aufträgen im Multitaskformat wird das Feld tasks, ein Array von TaskSettings-Datenstrukturen, in das JobSettings-Objekt aufgenommen. Einige Felder, die zuvor Teil von JobSettings waren, sind jetzt Teil der Aufgabeneinstellungen für Aufträge im Multitaskformat. JobSettings wird ebenfalls aktualisiert, sodass das Feld format eingeschlossen wird. Das format-Feld zeigt das Format des Auftrags an und ist ein STRING-Wert, der auf SINGLE_TASK oder MULTI_TASK festgelegt ist.
Sie müssen Ihre vorhandenen API-Clients für diese Änderungen an JobSettings für Aufträge im Multitaskformat aktualisieren. Weitere Informationen zu erforderlichen Änderungen finden Sie im API-Clienthandbuch.
Die Auftrags-API 2.1 unterstützt das Multitaskformat. Alle API 2.1-Anforderungen müssen dem Multitaskformat entsprechen, und Antworten sind im Multitaskformat strukturiert. Neue Features werden zuerst für API 2.1 veröffentlicht.
Die Auftrags-API 2.0 wird mit einem zusätzlichen Feld aktualisiert, um Aufträge im Multitaskformat zu unterstützen. Sofern nicht anders angegeben, verwenden die Beispiele in diesem Dokument API 2.0. Databricks empfiehlt jedoch API 2.1 für neue und vorhandene API-Skripts und -Clients.
Ein JSON-Beispieldokument, das einen Auftrag im Multitaskformat für API 2.0 und 2.1 darstellt:
{
"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"
}
Die Auftrags-API 2.1 unterstützt die Konfiguration von Clustern auf Aufgabenebene oder eines oder mehrerer freigegebener Auftragscluster:
- Ein Cluster auf Aufgabenebene wird erstellt und gestartet, wenn eine Aufgabe startet, und wird beendet, wenn die Aufgabe abgeschlossen ist.
- Ein freigegebener Auftragscluster gestattet es mehreren Aufgaben im selben Auftrag, den Cluster zu verwenden. Der Cluster wird beim Start der ersten Aufgabe, die den Cluster nutzt, erstellt und gestartet. Der Cluster wird beendet, wenn die letzte Aufgabe, die den Cluster nutzt, abgeschlossen ist. Ein freigegebener Auftragscluster wird nicht beendet, wenn er sich im Leerlauf befindet – er wird erst beendet, wenn alle Aufgaben, die ihn nutzen, abgeschlossen sind. Mehrere nicht abhängige Aufgaben, die einen Cluster gemeinsam nutzen, können gleichzeitig gestartet werden. Wenn ein freigegebener Auftragscluster ausfällt oder beendet wird, bevor alle Aufgaben fertig gestellt wurden, wird ein neuer Cluster erstellt.
Zum Konfigurieren freigegebener Auftragscluster schließen Sie ein JobCluster-Array in das JobSettings-Objekt ein. Sie können maximal 100 Cluster pro Auftrag angeben. Im Folgenden finden Sie ein Beispiel für eine API 2.1-Antwort für einen Auftrag, der mit zwei freigegebenen Clustern konfiguriert ist:
Hinweis
Wenn eine Aufgabe Bibliotheksabhängigkeiten aufweist, müssen Sie die Bibliotheken in den Feldeinstellungen von task konfigurieren. Bibliotheken können nicht in der Konfiguration eines freigegebenen Auftragsclusters konfiguriert werden. Im folgenden Beispiel veranschaulicht das libraries-Feld in der Konfiguration der ingest_orders-Aufgabe die Spezifikation einer Bibliotheksabhängigkeit.
{
"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"
}
Bei Aufträgen im Einzeltaskformat bleibt die JobSettings-Datenstruktur unverändert, mit der Ausnahme, dass das Feld format hinzugefügt wird. Es ist kein TaskSettings-Array enthalten, und die Aufgabeneinstellungen bleiben auf der obersten Ebene der JobSettings-Datenstruktur definiert. Sie müssen keine Änderungen an Ihren vorhandenen API-Clients vornehmen, um Aufträge im Einzeltaskformat zu verarbeiten.
Ein JSON-Beispieldokument, das einen Auftrag im Einzeltaskformat für API 2.0 darstellt:
{
"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-Clienthandbuch
Dieser Abschnitt enthält Richtlinien, Beispiele und erforderliche Änderungen für API-Aufrufe, die von dem neuen Multitaskformat-Feature betroffen sind.
Inhalt dieses Abschnitts:
Erstellen
Um einen Auftrag im Einzeltaskformat über den Vorgang Create a new job (Neuen Auftrag erstellen) (POST /jobs/create) in der Auftrags-API zu erstellen, müssen Sie keine vorhandenen Clients ändern.
Um einen Auftrag im Multitaskformat zu erstellen, verwenden Sie das tasks-Feld in JobSettings, um Einstellungen für jede einzelne Aufgabe anzugeben. Im folgenden Beispiel wird ein Auftrag mit zwei Notebookaufgaben erstellt. Dieses Beispiel gilt für API 2.0 und 2.1:
Hinweis
Pro Auftrag können maximal 100 Aufgaben angegeben werden.
{
"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
}
]
}
Führt „Submit“ aus
Um eine einmalige Ausführung eines Auftrags im Einzeltaskformat mit dem Vorgang Create and trigger a one-time run (Einmalige Ausführung erstellen und auslösen) (POST /runs/submit) in der Auftrags-API zu übermitteln, müssen Sie keine vorhandenen Clients ändern.
Um eine einmalige Ausführung eines Auftrags im Multitaskformat zu übermitteln, verwenden Sie das tasks-Feld in JobSettings, um Einstellungen für jede Aufgabe anzugeben, einschließlich Clustern. Cluster müssen bei der Übermittlung eines Auftrags im Multitaskformat auf Aufgabenebene festgelegt werden, da die runs submit-Anforderung keine freigegebenen Auftragscluster unterstützt. Ein Beispiel für JobSettings, die mehrere Aufgaben angeben, finden Sie unter Create.
Aktualisieren
Um einen Auftrag im Einzeltaskformat mit dem Vorgang Partially update a job (Auftrag teilweise aktualisieren) (POST /jobs/update) in der Auftrags-API zu aktualisieren, müssen Sie keine vorhandenen Clients ändern.
Um die Einstellungen eines Auftrags im Multitaskformat zu aktualisieren, müssen Sie das eindeutige task_key-Feld verwenden, um neue task-Einstellungen zu identifizieren. Ein Beispiel für JobSettings, die mehrere Aufgaben angeben, finden Sie unter Create.
Zurücksetzen
Um die Einstellungen eines Auftrags im Einzelaufgabeformat mit dem Vorgang Overwrite all settings for a job (Alle Einstellungen eines Auftrags überschreiben) (POST /jobs/reset) in der Auftrags-API zu überschreiben, müssen Sie keine vorhandenen Clients ändern.
Um die Einstellungen eines Auftrags im Multitaskformat zu überschreiben, geben Sie eine JobSettings-Datenstruktur mit einem Array von TaskSettings-Datenstrukturen an. Ein Beispiel für JobSettings, die mehrere Aufgaben angeben, finden Sie unter Create.
Verwenden Sie Update, um einzelne Felder zu ändern, ohne vom Einzeltask- zum Multitaskformat zu wechseln.
Auflisten
Bei Aufträgen im Einzeltaskformat sind keine Clientänderungen erforderlich, um die Antwort des Vorgangs List all jobs (Alle Aufträge auflisten) (GET /jobs/list) in der Auftrags-API zu verarbeiten.
Bei Aufträgen im Multitaskformat werden die meisten Einstellungen auf Aufgabenebene und nicht auf Auftragsebene definiert. Die Clusterkonfiguration kann auf Aufgaben- oder Auftragsebene festgelegt werden. So ändern Sie Clients so, dass sie auf Cluster- oder Aufgabeneinstellungen für einen in der Job-Struktur zurückgegebenen Auftrag im Multitaskformat zugreifen können
- Analysieren Sie das
job_id-Feld für den Auftrag im Multitaskformat. - Übergeben Sie die
job_idan den Vorgang Get a job (Auftrag abrufen) (GET /jobs/get) in der Auftrags-API, um Auftragsdetails abzurufen. Eine Beispielantwort des API-AufrufsGetfür einen Auftrag im Multitaskformat finden Sie unter Get.
Das folgende Beispiel zeigt eine Antwort, die Aufträge im Einzeltask- und Multitaskformat enthält. Dieses Beispiel gilt für 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"
}
]
}
Abrufen
Bei Aufträgen im Einzeltaskformat sind keine Clientänderungen erforderlich, um die Antwort des Vorgangs Get a job (Auftrag abrufen) (GET /jobs/get) in der Auftrags-API zu verarbeiten.
Aufträge im Multitaskformat geben ein Array von task-Datenstrukturen zurück, die Aufgabeneinstellungen enthalten. Wenn Sie Zugriff auf Details auf Aufgabenebene benötigen, müssen Sie Ihre so Clients ändern, dass sie das tasks-Array durchlaufen und erforderliche Felder extrahieren.
Im Folgenden sehen Sie eine Beispielantwort des API-Aufrufs Get für einen Auftrag im Multitaskformat. Dieses Beispiel gilt für API 2.0 und 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"
}
Führt „Abrufen“ aus
Bei Aufträgen im Einzeltaskformat sind keine Clientänderungen erforderlich, um die Antwort des Vorgangs Get a job run (Auftragsausführung abrufen) (GET /jobs/runs/get) in der Auftrags-API zu verarbeiten.
Die Antwort für die Ausführung eines Auftrags im Multitaskformat enthält ein Array von TaskSettings. So rufen Sie Ausführungsergebnisse für jede Aufgabe ab
- Durchlaufen Sie die einzelnen Aufgaben.
- Analysieren Sie die
run_idfür jede Aufgabe. - Rufen Sie den Vorgang Get the output for a run (Ausgabe für eine Ausführung abrufen) (
GET /jobs/runs/get-output) mit derrun_idauf, um Details zur Ausführung jeder Aufgabe zu erhalten. Im Folgenden finden Sie eine Beispielantwort dieser Anforderung:
{
"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"
}
Führt „Ausgabe abrufen“ aus
Bei Aufträgen im Einzeltaskformat sind keine Clientänderungen erforderlich, um die Antwort des Vorgangs Get the output for a run (Ausgabe für eine Ausführung abrufen) (GET /jobs/runs/get-output) in der Auftrags-API zu verarbeiten.
Bei Aufträgen im Multitaskformat führt der Aufruf von Runs get output für eine übergeordnete Ausführung zu einem Fehler, da die Ausführungsausgabe nur für einzelne Aufgaben verfügbar ist. So rufen Sie die Ausgabe und die Metadaten für einen Auftrag im Multitaskformat ab
- Rufen Sie die Anforderung Get the output for a run (Ausgabe für eine Ausführung abrufen) auf.
- Durchlaufen Sie die untergeordneten
run_id-Felder in der Antwort. - Verwenden Sie die untergeordneten
run_id-Werte zum Aufrufen vonRuns get output.
Führt „Auflisten“ aus
Bei Aufträgen im Einzeltaskformat sind keine Clientänderungen erforderlich, um die Antwort des Vorgangs List runs for a job (Ausführungen für einen Auftrag auflisten) (GET /jobs/runs/list) zu verarbeiten.
Für Aufträge im Multitaskformat wird ein leeres tasks-Array zurückgegeben. Übergeben Sie die run_id an den Vorgang Get a job run (Eine Auftragsausführung abrufen) (GET /jobs/runs/get), um die Aufgaben abzurufen. Im Folgenden sehen Sie eine Beispielantwort des API-Aufrufs Runs list für einen Auftrag im Multitaskformat:
{
"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
}