Dela via

Uppdaterar från Jobb-API 2.0 till 2.1

  • Artikel

Nu kan du orkestrera flera uppgifter med Azure Databricks jobb. Den här artikeln beskriver ändringar i API:et för jobb som stöder jobb med flera uppgifter och har 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 enaktivitetsformat och jobb som definierats med flera aktiviteter som format för flera aktiviteter.

Jobs API 2.0 och 2.1 stödjer nu -uppdatering-begäran. Använd update-begäran för att ändra ett befintligt jobb istället för -återställningsbegäran för att minimera ändringar mellan jobb med enkel 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 ingår fältet tasks, en matris med TaskSettings datastrukturer, i JobSettings-objektet. Vissa fält som tidigare ingick i JobSettings ingår nu i aktivitetsinställningarna för jobb i flera aktivitetsformat. 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 JobSettings 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 det här formatet och svaren är strukturerade i det här formatet.

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:

Not

Om en aktivitet har biblioteksberoenden måste du konfigurera biblioteken i task fältinställningar. bibliotek kan inte konfigureras i en klusterkonfiguration för delat jobb. I följande exempel visar fältet libraries i konfigurationen av den ingest_orders uppgiften specifikation av 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 med ett enkelt uppgiftsformat förblir datastrukturen JobSettings oförändrad med undantag för tillägget av format-fältet. Ingen TaskSettings matris ingår och aktivitetsinställningarna förblir definierade på den översta nivån i JobSettings datastruktur. Du behöver inte göra ändringar i dina befintliga API-klienter för att bearbeta jobb i ett enkeluppgiftsformat.

Ett exempel på ett JSON-dokument som representerar ett enskilt uppgiftersformat jobb 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.

I det här avsnittet:

Skapa

Om du vill skapa ett jobb med en uppgiftsformat via Skapa ett nytt jobb åtgärd (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:

Not

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

körningar skickas in

Om du vill skicka en engångskörning av ett enkeluppgiftsformatjobb 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 uppgifter använder du fältet tasks i JobSettings för att ange inställningar för varje aktivitet, inklusive kluster. Kluster måste anges på aktivitetsnivå när ett jobb i fleruppgiftsformat skickas eftersom runs submit-begäran inte stöder delade jobbkluster. Se Skapa för ett exempel på att ange flera aktiviteter JobSettings.

Uppdatering

Om du vill uppdatera ett enaktivitetsformatjobb med Uppdatera delvis ett jobb åtgärd (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 fältet task_key för att identifiera nya task inställningar. Se Skapa för ett exempel JobSettings ange flera aktiviteter.

Återställ

Om du vill skriva över inställningarna för ett jobb i enaktivitetsformat med åtgärden Överskriv alla inställningar för ett jobb (POST /jobs/reset) i API:et för jobb 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 med TaskSettings datastrukturer. Titta på Skapa för ett exempel JobSettings som anger flera aktiviteter.

Använd uppdatering för att ändra enskilda fält utan att växla från enkel- till fleruppgiftsformat.

lista

För jobb med en uppgift krävs inga klientändringar för att bearbeta svaret från Lista alla jobb åtgärd (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 modifierar du klienter för att få tillgång till kluster- och uppgiftsinställningar för ett multitask-uppdrag som returneras i Job-strukturen:

  • Analysera fältet job_id för multi-task format-arbetet.
  • Skicka job_id till Hämta-jobb-åtgärden (GET /jobs/get) i Jobb-API:t för att hämta jobbinformation. Se Hämta för ett exempelsvar från Get API-anropet för ett jobb med flera uppgifter.

I följande exempel visas ett svar som innehåller jobb i formatet för enstaka uppgifter och flera uppgifter. 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"
    }
  ]
}

Hämta

För jobb i enkelformatsformat krävs inga ändringar av klienten för att bearbeta svaret från Hämta ett jobb operationen (GET /jobs/get) i jobb-API.

Jobb i fleraktivitetsformat 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 via tasks-matrisen och extrahera obligatoriska fält.

Följande visar ett exempelsvar från Get API-anropet 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"
}

Körningar hämta

För jobb med en uppgift krävs inga klientändringar för att bearbeta svaret från Hämta en jobbkörning åtgärd (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 ger utdata

För jobb i en enkel uppgiftsformat krävs inga klientändringar för att bearbeta svaret från Hämta utdata för en körning operation (GET /jobs/runs/get-output) i Jobs API.

Om du anropar Runs get output på en överordnad kör för fleruppgiftsjobb resulterar det 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:

lista över körningar

För jobb med ett enkeluppgiftsformat krävs inga klientändringar för att bearbeta svaret från körningen av -listan för jobboperation (GET /jobs/runs/list).

För jobb med flera uppgiftsformat returneras en tom tasks-matris. Skicka run_id till Get a job run operation (GET /jobs/runs/get) för att hämta aktiviteterna. Följande visar ett exempelsvar från Runs list API-anrop 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
}