Udostępnij za pośrednictwem

Aktualizacja Jobs API z wersji 2.0 do 2.1

  • Artykuł

Teraz można orkiestrować wiele zadań za pomocą usługi Azure Databricks zadań. Ten artykuł zawiera szczegółowe informacje o zmianach w API zadań , które obsługują zadania z wieloma podzadaniami oraz zawierają wskazówki ułatwiające aktualizację obecnych aplikacji klienckich API w celu pracy z tą nową funkcją.

Databricks zaleca użycie Jobs API w wersji 2.1 dla skryptów interfejsów API i klientów, szczególnie w przypadku korzystania z prac z wieloma zadaniami.

W tym artykule opisano zadania zdefiniowane przy użyciu jednego zadania jako format jednozadaniowy , a zadania zdefiniowane z wieloma zadaniami jako format wielozadaniowy .

Jobs API 2.0 i 2.1 teraz obsługują żądanie aktualizacji . Użyj żądania update, aby zmienić istniejące zadanie zamiast korzystać z żądania reset, aby zminimalizować zmiany między zadaniami w formacie pojedynczego zadania a zadaniami w formacie wielu zadań.

Zmiany interfejsu API

API pracy obecnie definiuje obiekt TaskSettings do zapisywania ustawień dla każdego procesu w pracy. W przypadku zadań w formacie wielozadaniowym pole tasks, będące tablicą struktur danych TaskSettings, jest zawarte w obiekcie JobSettings. Niektóre pola, które wcześniej były częścią JobSettings, są teraz częścią ustawień zadań w formacie wielozadaniowym. JobSettings jest również aktualizowana w celu uwzględnienia pola format. Pole format wskazuje format zadania i jest wartością STRING ustawioną na SINGLE_TASK lub MULTI_TASK.

Musisz zaktualizować obecne klienty API, aby wprowadzić te zmiany w JobSettings dla zadań wielozadaniowych. Aby uzyskać więcej informacji na temat wymaganych zmian, zobacz przewodnik klienta interfejsu API .

Jobs API 2.1 obsługuje format wielu zadań. Wszystkie żądania interfejsu API 2.1 muszą być zgodne z tym formatem, a odpowiedzi mają strukturę w tym formacie.

Interfejs API zadań 2.0 został zaktualizowany o dodatkowe pole do obsługi zadań w formacie wielu zadań. Z wyjątkiem przypadków, w których wspomniano, przykłady w tym dokumencie używają interfejsu API 2.0. Jednak usługa Databricks zaleca interfejs API 2.1 dla nowych i istniejących skryptów i klientów interfejsu API.

Przykładowy dokument JSON reprezentujący zadanie w formacie wielozadaniowym dla interfejsu API 2.0 i 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"
}

Interfejs API zadań 2.1 obsługuje konfigurację klastrów poziomu zadań lub co najmniej jednego udostępnionego klastra zadań:

  • Klaster poziomu zadań jest tworzony i uruchamiany wraz z rozpoczęciem zadania, a kończy się, gdy zadanie zostanie zakończone.
  • Udostępniony klaster zadań umożliwia używanie klastra wielu zadań w tym samym zadaniu. Klaster jest tworzony i uruchamiany, gdy pierwsze zadanie przy użyciu klastra zostanie uruchomione i zakończone po zakończeniu ostatniego zadania przy użyciu klastra. Udostępniony klaster zadań nie jest wyłączany podczas bezczynności, ale zostaje zamknięty dopiero po zakończeniu wszystkich zadań, które go używają. Wiele niezależnych zadań współużytkowania klastra można uruchomić w tym samym czasie. Jeśli klaster zadań udostępnionych zakończy się niepowodzeniem lub zostanie zakończony przed zakończeniem wszystkich zadań, zostanie utworzony nowy klaster.

Aby skonfigurować klastry zadań udostępnionych, dołącz tablicę JobCluster w obiekcie JobSettings. Można określić maksymalnie 100 klastrów na zadanie. Poniżej przedstawiono przykład odpowiedzi interfejsu API 2.1 dla zadania skonfigurowanego z dwoma udostępnionymi klastrami:

Notatka

Jeśli zadanie ma zależności od bibliotek, należy skonfigurować biblioteki w ustawieniach pola task; nie można skonfigurować bibliotek w konfiguracji współdzielonego klastra zadań. W poniższym przykładzie pole libraries w konfiguracji zadania ingest_orders pokazuje specyfikację zależności biblioteki.

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

W przypadku zadań w formacie pojedynczego zadania struktura danych JobSettings pozostaje niezmieniona z wyjątkiem dodawania pola format. Nie jest uwzględniona tablica TaskSettings, a ustawienia zadań pozostają zdefiniowane na najwyższym poziomie struktury danych JobSettings. Nie trzeba wprowadzać zmian w istniejących klientach interfejsu API w celu przetwarzania zadań w formacie pojedynczego zadania.

Przykładowy dokument JSON reprezentujący format zadania jednorazowego dla interfejsu 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"
}

Przewodnik klienta API

Ta sekcja zawiera wskazówki, przykłady i wymagane zmiany wywołań interfejsu API, których dotyczy nowa funkcja formatu wielu zadań.

W tej sekcji:

Tworzenie

Aby utworzyć zadanie w formacie pojedynczego zadania za pomocą operacji Utwórz nowe zadanie (POST /jobs/create) w interfejsie API zadań, nie trzeba zmieniać istniejących klientów.

Aby utworzyć zadanie w formacie wielu zadań, użyj pola tasks w JobSettings, aby określić ustawienia dla każdego zadania. Poniższy przykład tworzy zadanie z dwoma zadaniami notatnika. Ten przykład dotyczy interfejsów API 2.0 i 2.1:

Notatka

Można określić maksymalnie 100 zadań na zadanie.

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

Przebiegi przesyłania

Aby przesłać jednokrotne uruchomienie zadania w formacie pojedynczego zadania za pomocą operacji Tworzenie i uruchamianie jednorazowego zadania (POST /runs/submit) w interfejsie API zadań, nie trzeba zmieniać istniejących klientów.

Aby przesłać jednorazowe uruchomienie zadania w formacie wielozadaniowym, użyj pola tasks w JobSettings, aby określić ustawienia dla każdego zadania, w tym klastrów. Klastry muszą być ustawione na poziomie zadania podczas przesyłania zadania w formacie wielu zadań, ponieważ żądanie runs submit nie obsługuje klastrów zadań udostępnionych. Zobacz Tworzenie, aby zapoznać się z przykładem JobSettings określania wielu zadań.

Aktualizacja

Aby zaktualizować zadanie w formacie pojedynczego zadania przy użyciu operacji Częściowa aktualizacja zadania (POST /jobs/update) w API zadań, nie wymaga zmiany istniejących klientów.

Aby zaktualizować ustawienia zadania w formacie wielu zadań, należy użyć unikatowego pola task_key, aby zidentyfikować nowe ustawienia task. Zobacz Utwórz, aby zapoznać się z przykładem JobSettings określającego wiele zadań.

resetowanie

Aby zastąpić ustawienia zadania w formacie jednoprocesowym za pomocą operacji Zastąp wszystkie ustawienia zadania (POST /jobs/reset) w interfejsie API zadań, nie trzeba zmieniać istniejących klientów.

Aby zastąpić konfiguracje zadania formatu wielozadaniowego, określ strukturę danych JobSettings zawierającą tablicę struktur danych TaskSettings. Zobacz Tworzenie, aby zapoznać się z przykładem JobSettings określania wielu zadań.

Użyj Update, aby zmienić poszczególne pola bez przełączania się z pojedynczego zadania na format wielu zadań.

lista

W przypadku zadań w formacie jednokrotnego zadania nie są wymagane żadne zmiany po stronie klienta do przetworzenia odpowiedzi z operacji Wyświetl wszystkie zadania (GET /jobs/list) w interfejsie API zadań.

W przypadku zadań w formacie wielu zadań większość ustawień jest definiowana na poziomie zadania, a nie na poziomie zadania. Konfigurację klastra można ustawić na poziomie zadania lub procesu. Aby zmodyfikować klientów w celu uzyskania dostępu do klastra lub ustawień zadań dla zadania w formacie wielu zadań zwróconych w strukturze Job:

  • Przeanalizuj pole job_id dla zadania w formacie multitaskowym.
  • Przekaż job_id do Pobierz operację zadania (GET /jobs/get) w interfejsie API zadań, aby pobrać szczegóły zadania. Zobacz Get, aby uzyskać przykładową odpowiedź wywołania interfejsu API Get dla zadania w formacie wielu zadań.

W poniższym przykładzie przedstawiono odpowiedź zawierającą zadania w formacie pojedynczego zadania i wielu zadań. Ten przykład dotyczy interfejsu 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"
    }
  ]
}

Pobierz

W przypadku zadań w formacie zadania pojedynczego żadne zmiany po stronie klienta nie są wymagane do przetworzenia odpowiedzi z Get a job operation (GET /jobs/get) w interfejsie API Jobs.

Zadania w formacie multi-task zwracają tablicę task struktur danych zawierających ustawienia zadań. Jeśli potrzebujesz dostępu do szczegółowych informacji na poziomie zadań, musisz zmodyfikować swoje aplikacje klienckie, aby iterowały przez tablicę tasks i wyodrębniły konieczne pola.

Poniżej przedstawiono przykładową odpowiedź wywołania interfejsu API Get dla zadania o formacie wielozadaniowym. Ten przykład dotyczy interfejsów API 2.0 i 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"
}

Uzyskiwanie przebiegów

W przypadku zadań w formacie pojedynczego zadania nie są wymagane żadne zmiany po stronie klienta, aby przetworzyć odpowiedź z operacji Get a job run (GET /jobs/runs/get) w API zadań.

Odpowiedź na uruchomienie zadania w formacie dla wielu zadań zawiera tablicę TaskSettings. Aby pobrać wyniki wykonania dla każdego zadania:

  • Przejdź przez każde z zadań.
  • Przeanalizuj run_id dla każdego zadania.
  • Wywołaj Pobierz dane wyjściowe dla operacji uruchamiania (GET /jobs/runs/get-output) przy użyciu run_id, aby uzyskać szczegółowe informacje na temat przebiegu dla każdego zadania. Poniżej przedstawiono przykładową odpowiedź z tego żądania:
{
  "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"
}

Uruchomienia generują dane wyjściowe

W przypadku zadań w formacie pojedynczego zadania, nie są wymagane żadne zmiany po stronie klienta, aby przetworzyć odpowiedź z uzyskania danych wyjściowych dla operacji przebiegu (GET /jobs/runs/get-output) w API Zadań.

W przypadku zadań wielozadaniowych wywoływanie Runs get output w procesie nadrzędnym powoduje błąd, ponieważ wynik uruchomienia jest dostępny tylko dla poszczególnych zadań. Aby pobrać wyniki i metadane pracy w formacie wielozadaniowym:

lista przebiegów

W przypadku zadań pojedynczego formatu nie są wymagane żadne zmiany klienta do przetworzenia odpowiedzi z operacji listy uruchomień dla zadania ().

W przypadku zadań w formacie wielozadaniowym zwracana jest pusta tablica tasks. Przekaż run_id do Get a job run operation (GET /jobs/runs/get), aby pobrać zadania. Poniżej przedstawiono przykładową odpowiedź z wywołania interfejsu API Runs list dla zadania w formacie wielozadaniowym:

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