Aktualizowanie z interfejsu API zadań 2.0 do 2.1

  • Artykuł

Teraz można organizować wiele zadań za pomocą zadań usługi Azure Databricks. Ten artykuł zawiera szczegółowe informacje o zmianach w interfejsie API zadań obsługujących zadania z wieloma zadaniami i zawiera wskazówki ułatwiające aktualizowanie istniejących klientów interfejsu API w celu pracy z tą nową funkcją.

Usługa Databricks zaleca interfejs API zadań w wersji 2.1 dla skryptów interfejsu API i klientów, szczególnie w przypadku korzystania z zadań z wieloma zadaniami.

W tym artykule opisano zadania zdefiniowane za pomocą jednego zadania jako format pojedynczego zadania i zadania zdefiniowane z wieloma zadaniami jako format wielu zadań.

Interfejs API zadań w wersji 2.0 i 2.1 obsługuje teraz żądanie aktualizacji . update Użyj żądania , aby zmienić istniejące zadanie zamiast żądania resetowania, aby zminimalizować zmiany między zadaniami w formacie pojedynczego zadania i zadaniami w formacie wielu zadań.

Zmiany w interfejsie API

Interfejs API zadań definiuje TaskSettings teraz obiekt do przechwytywania ustawień dla każdego zadania w zadaniu. W przypadku zadań tasks w formacie wielu zadań pole, tablica TaskSettings struktur danych, jest uwzględniana w JobSettings obiekcie. Niektóre pola, które wcześniej JobSettings były częścią zadania, są teraz częścią ustawień zadań w formacie wielu zadań. JobSettings program jest również aktualizowany w format celu uwzględnienia pola. Pole format wskazuje format zadania i jest wartością ustawioną STRING na SINGLE_TASK lub MULTI_TASK.

Musisz zaktualizować istniejących klientów interfejsu API, aby wprowadzić te zmiany w obszarze Zadanie Ustawienia dla zadań w formacie wielu zadań. Aby uzyskać więcej informacji na temat wymaganych zmian, zobacz przewodnik klienta interfejsu API.

Interfejs API zadań 2.1 obsługuje format wielu zadań. Wszystkie żądania interfejsu API 2.1 muszą być zgodne z formatem wielu zadań i odpowiedziami mają strukturę w formacie wielodaniowym. Nowe funkcje są wydawane najpierw dla interfejsu API 2.1.

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 formatu wielu zadań 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 po uruchomieniu i zakończeniu zadania po zakończeniu zadania.
  • 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 przerywany w przypadku bezczynności, ale kończy się dopiero po zakończeniu wszystkich zadań podrzędnych. 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 do JobSettings obiektu . 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:

Uwaga

Jeśli zadanie ma zależności biblioteki, należy skonfigurować biblioteki w task ustawieniach pola; biblioteki nie można skonfigurować w konfiguracji udostępnionego klastra zadań. W poniższym przykładzie libraries pole w konfiguracji ingest_orders zadania demonstruje 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ń JobSettings w formacie pojedynczego zadania struktura danych pozostaje niezmieniona z wyjątkiem dodawania format pola. Tablica nie TaskSettings jest dołączona, a ustawienia zadań pozostają zdefiniowane na najwyższym poziomie JobSettings struktury danych. Nie trzeba wprowadzać zmian w istniejących klientach interfejsu API w celu przetwarzania zadań w formacie pojedynczego zadania.

Przykładowy dokument JSON reprezentujący zadanie formatu pojedynczego zadania 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 interfejsu 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:

Utworzyć

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

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

Uwaga

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

Przesyłanie przebiegów

Aby przesłać jednorazowe uruchomienie zadania w formacie pojedynczego zadania z operacją Tworzenia i wyzwalania jednorazowej operacji uruchamiania (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 tasks pola w , JobSettings aby określić ustawienia dla każdego zadania, w tym klastrów. Klastry muszą być ustawiane na poziomie zadania podczas przesyłania zadania w formacie wielu zadań, ponieważ runs submit żądanie nie obsługuje udostępnionych klastrów zadań. Zobacz Tworzenie , aby zapoznać się z przykładem JobSettings określającym wiele zadań.

Aktualizacji

Aby zaktualizować zadanie formatu pojedynczego zadania za pomocą operacji Częściowej aktualizacji zadania (POST /jobs/update) w interfejsie API zadań, nie trzeba zmieniać istniejących klientów.

Aby zaktualizować ustawienia zadania w formacie wielu zadań, należy użyć unikatowego task_key pola w celu zidentyfikowania nowych task ustawień. Zobacz Tworzenie , aby zapoznać się z przykładem JobSettings określającym wiele zadań.

Zresetować

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

Aby zastąpić ustawienia zadania formatu wielozadaniowego, określ JobSettings strukturę danych z tablicą TaskSettings struktur danych. Zobacz Tworzenie , aby zapoznać się z przykładem JobSettings określającym wiele zadań.

Użyj opcji Aktualizuj , aby zmienić poszczególne pola bez przełączania z jednego zadania na format wielu zadań.

Listy

W przypadku zadań w formacie pojedynczego zadania żadne zmiany klienta nie są wymagane 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 zadania. Aby zmodyfikować klientów w celu uzyskania dostępu do klastra lub ustawień zadań dla zadania w formacie wielu zadań zwróconych w Job strukturze:

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 pojedynczego zadania żadne zmiany klienta nie są wymagane do przetworzenia odpowiedzi z operacji Pobierz zadanie (GET /jobs/get) w interfejsie API zadań.

Zadania w formacie wielozadaniowym zwracają tablicę task struktur danych zawierających ustawienia zadań. Jeśli potrzebujesz dostępu do szczegółów poziomu zadań, musisz zmodyfikować klientów, aby iterowali przez tablicę tasks i wyodrębnili wymagane pola.

Poniżej przedstawiono przykładową odpowiedź wywołania interfejsu Get API dla zadania w formacie wielu zadań. 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"
}

Pobieranie przebiegów

W przypadku zadań w formacie pojedynczego zadania żadne zmiany klienta nie są wymagane do przetworzenia odpowiedzi z operacji Pobierania uruchomienia zadania (GET /jobs/runs/get) w interfejsie API zadań.

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

  • Iterowanie po każdym z zadań podrzędnych.
  • Przeanalizuj element run_id dla każdego zadania.
  • Wywołaj polecenie Pobierz dane wyjściowe dla operacji uruchamiania () za pomocą polecenia run_id ,GET /jobs/runs/get-output 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 pobierają dane wyjściowe

W przypadku zadań w formacie pojedynczego zadania żadne zmiany klienta nie są wymagane do przetworzenia odpowiedzi z polecenia Pobierz dane wyjściowe dla operacji uruchamiania (GET /jobs/runs/get-output) w interfejsie API zadań.

W przypadku zadań w formacie wielozadaniowym wywołanie Runs get output nadrzędnego przebiegu powoduje błąd, ponieważ dane wyjściowe uruchomienia są dostępne tylko dla poszczególnych zadań. Aby pobrać dane wyjściowe i metadane zadania w formacie wielu zadań:

Lista przebiegów

W przypadku zadań w formacie pojedynczego zadania żadne zmiany klienta nie są wymagane do przetworzenia odpowiedzi z uruchomienia listy dla operacji zadania (GET /jobs/runs/list).

W przypadku zadań w formacie wielu zadań zwracana jest pusta tasks tablica. Przekaż element run_id do operacji Pobierania uruchomienia zadania (GET /jobs/runs/get), aby pobrać zadania. Poniżej przedstawiono przykładową odpowiedź wywołania interfejsu Runs list API dla zadania w formacie wielu zadań:

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