Uppdaterar från Jobb-API 2.0 till 2.1

Artikel
03/01/2024

Nu kan du orkestrera flera uppgifter med Azure Databricks-jobb. Den här artikeln beskriver ändringar i jobb-API:et som stöder jobb med flera uppgifter och ger vägledning som hjälper dig att uppdatera dina befintliga API-klienter så att de fungerar med den här nya funktionen.

Databricks rekommenderar Jobb-API 2.1 för dina API-skript och -klienter, särskilt när du använder jobb med flera uppgifter.

Den här artikeln refererar till jobb som definierats med en enskild uppgift som en uppgiftsformat och jobb som definierats med flera aktiviteter som format för flera aktiviteter.

Jobb-API 2.0 och 2.1 stöder nu uppdateringsbegäran. update Använd begäran om att ändra ett befintligt jobb i stället för återställningsbegäran för att minimera ändringarna mellan jobb med en uppgiftsformat och jobb med flera uppgifter.

API-ändringar

Jobb-API:et definierar nu ett TaskSettings objekt för att samla in inställningar för varje uppgift i ett jobb. För jobb med flera uppgifter inkluderas fältet tasks , en matris med TaskSettings datastrukturer, i JobSettings objektet. Vissa fält som tidigare ingick JobSettings i ingår nu i aktivitetsinställningarna för jobb med flera uppgifter. JobSettings uppdateras också för att inkludera fältet format . Fältet format anger jobbets format och är ett STRING värde inställt på SINGLE_TASK eller MULTI_TASK.

Du måste uppdatera dina befintliga API-klienter för dessa ändringar i Jobb Inställningar för jobb med flera uppgifter. Mer information om nödvändiga ändringar finns i API-klientguiden .

Jobb-API 2.1 stöder formatet för flera aktiviteter. Alla API 2.1-begäranden måste överensstämma med formatet för flera aktiviteter och svaren är strukturerade i formatet för flera aktiviteter. Nya funktioner släpps för API 2.1 först.

Jobb-API 2.0 uppdateras med ytterligare ett fält för att stödja jobb i flera aktivitetsformat. Förutom där det anges använder exemplen i det här dokumentet API 2.0. Databricks rekommenderar dock API 2.1 för nya och befintliga API-skript och -klienter.

Ett exempel på ett JSON-dokument som representerar ett jobb med flera uppgifter för API 2.0 och 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"
}

Jobb-API 2.1 stöder konfiguration av kluster på aktivitetsnivå eller ett eller flera delade jobbkluster:

Ett kluster på aktivitetsnivå skapas och startas när en aktivitet startar och avslutas när aktiviteten är klar.
Med ett delat jobbkluster kan flera aktiviteter i samma jobb använda klustret. Klustret skapas och startas när den första uppgiften med hjälp av klustret startar och avslutas efter att den sista uppgiften med hjälp av klustret har slutförts. Ett delat jobbkluster avslutas inte när det är inaktivt, men avslutas först när alla aktiviteter som använder det har slutförts. Flera icke-beroende uppgifter som delar ett kluster kan starta samtidigt. Om ett delat jobbkluster misslyckas eller avslutas innan alla aktiviteter har slutförts skapas ett nytt kluster.

Om du vill konfigurera delade jobbkluster inkluderar du en JobCluster matris i JobSettings objektet. Du kan ange högst 100 kluster per jobb. Följande är ett exempel på ett API 2.1-svar för ett jobb som konfigurerats med två delade kluster:

Kommentar

Om en aktivitet har biblioteksberoenden måste du konfigurera biblioteken task i fältinställningarna. Bibliotek kan inte konfigureras i en klusterkonfiguration för delat jobb. I följande exempel visar fältet libraries i konfigurationen ingest_orders av uppgiften specifikationen för ett biblioteksberoende.

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

För jobb JobSettings med en uppgiftsformat förblir datastrukturen oförändrad förutom att fältet läggs till format . Ingen TaskSettings matris ingår och aktivitetsinställningarna förblir definierade på den översta nivån i JobSettings datastrukturen. Du behöver inte göra ändringar i dina befintliga API-klienter för att bearbeta jobb med en uppgiftsformat.

Ett exempel på ett JSON-dokument som representerar ett jobb med en uppgiftsformat för 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"
}

API-klientguide

Det här avsnittet innehåller riktlinjer, exempel och nödvändiga ändringar för API-anrop som påverkas av den nya multiaktivitetsformatfunktionen.

Skapa

Om du vill skapa ett jobb med en uppgiftsformat via åtgärden Skapa ett nytt jobb (POST /jobs/create) i JOBB-API:et behöver du inte ändra befintliga klienter.

Om du vill skapa ett jobb med flera uppgifter använder du fältet tasks i JobSettings för att ange inställningar för varje aktivitet. I följande exempel skapas ett jobb med två notebook-uppgifter. Det här exemplet gäller API 2.0 och 2.1:

Kommentar

Högst 100 aktiviteter kan anges per jobb.

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

Skicka körningar

Om du vill skicka en engångskörning av ett enaktivitetsformatjobb med åtgärden Skapa och utlösa en engångskörning (POST /runs/submit) i jobb-API:et behöver du inte ändra befintliga klienter.

Om du vill skicka en engångskörning av ett jobb med flera aktiviteter använder du tasks fältet i JobSettings för att ange inställningar för varje aktivitet, inklusive kluster. Kluster måste anges på aktivitetsnivå när du skickar ett jobb med flera uppgifter eftersom runs submit begäran inte stöder delade jobbkluster. Se Skapa för ett exempel JobSettings som anger flera uppgifter.

Uppdatering

Om du vill uppdatera ett jobb med en uppgiftsformat med åtgärden Delvis uppdatera ett jobb (POST /jobs/update) i jobb-API:et behöver du inte ändra befintliga klienter.

Om du vill uppdatera inställningarna för ett jobb med flera uppgifter måste du använda det unika task_key fältet för att identifiera nya task inställningar. Se Skapa för ett exempel JobSettings som anger flera uppgifter.

Återställa

Om du vill skriva över inställningarna för ett enaktivitetsformatjobb med Skriv över alla inställningar för en jobbåtgärd (POST /jobs/reset) i jobb-API:et behöver du inte ändra befintliga klienter.

Om du vill skriva över inställningarna för ett jobb med flera uppgifter anger du en JobSettings datastruktur med en matris TaskSettings med datastrukturer. Se Skapa för ett exempel JobSettings som anger flera uppgifter.

Använd Uppdatera om du vill ändra enskilda fält utan att växla från en aktivitet till fleraktivitetsformat.

Lista

För jobb med en uppgift krävs inga klientändringar för att bearbeta svaret från åtgärden Lista alla jobb (GET /jobs/list) i jobb-API:et.

För jobb med flera uppgifter definieras de flesta inställningar på aktivitetsnivå och inte på jobbnivå. Klusterkonfigurationen kan anges på aktivitets- eller jobbnivå. Så här ändrar du klienter för att komma åt kluster- eller aktivitetsinställningar för ett jobb med flera uppgifter som returneras i Job strukturen:

Parsa fältet job_id för multiaktivitetsformatjobbet.
job_id Skicka till åtgärden Hämta ett jobb (GET /jobs/get) i jobb-API:et för att hämta jobbinformation. Se Hämta ett exempelsvar från API-anropet Get för ett jobb med flera uppgifter.

I följande exempel visas ett svar som innehåller jobb med en uppgift och flera aktiviteter. Det här exemplet gäller 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"
    }
  ]
}

Få

För jobb med en uppgift krävs inga klientändringar för att bearbeta svaret från åtgärden Hämta ett jobb (GET /jobs/get) i jobb-API:et.

Jobb med flera aktivitetsformat returnerar en matris med task datastrukturer som innehåller aktivitetsinställningar. Om du behöver åtkomst till information på aktivitetsnivå måste du ändra dina klienter så att de itererar genom matrisen tasks och extraherar obligatoriska fält.

Följande visar ett exempelsvar från API-anropet Get för ett jobb med flera uppgifter. Det här exemplet gäller API 2.0 och 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"
}

Hämta körningar

För jobb med en uppgift krävs inga klientändringar för att bearbeta svaret från åtgärden Hämta en jobbkörning (GET /jobs/runs/get) i jobb-API:et.

Svaret för en jobbkörning i flera uppgiftsformat innehåller en matris med TaskSettings. Så här hämtar du körningsresultat för varje aktivitet:

Iterera genom var och en av uppgifterna.
Parsa run_id för varje aktivitet.
Anropa Hämta utdata för en körningsåtgärd (GET /jobs/runs/get-output) med run_id för att få information om körningen för varje aktivitet. Följande är ett exempelsvar från den här begäran:

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

Körningar får utdata

För jobb med en uppgift krävs inga klientändringar för att bearbeta svaret från Hämta utdata för en körningsåtgärd (GET /jobs/runs/get-output) i jobb-API:et.

För jobb med flera uppgifter resulterar anrop Runs get output på en överordnad körning i ett fel eftersom körningsutdata endast är tillgängliga för enskilda uppgifter. Så här hämtar du utdata och metadata för ett jobb med flera uppgifter:

Anropa Hämta utdata för en körningsbegäran.
Iterera över de underordnade run_id fälten i svaret.
Använd underordnade run_id värden för att anropa Runs get output.

Lista över körningar

För jobb med en uppgiftsformat krävs inga klientändringar för att bearbeta svaret från listkörningarna för en jobbåtgärd (GET /jobs/runs/list).

För jobb med flera uppgifter returneras en tom tasks matris. run_id Skicka till åtgärden Hämta en jobbkörning (GET /jobs/runs/get) för att hämta aktiviteterna. Följande visar ett exempelsvar från API-anropet Runs list för ett jobb med flera uppgifter:

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