Bijwerken van de Jobs-API van 2.0 naar 2.1

U kunt nu meerdere taken organiseren met Azure Databricks taken. In dit artikel vindt u informatie over wijzigingen in de Taken-API die taken met meerdere taken ondersteunt en bevat richtlijnen waarmee u uw bestaande API-clients kunt bijwerken om met deze nieuwe functie te werken.

Databricks raadt Jobs API 2.1 aan voor uw API-scripts en -clients, met name wanneer u taken met meerdere taken gebruikt.

Dit artikel verwijst naar taken die zijn gedefinieerd met één taak als indeling voor één taak en taken die zijn gedefinieerd met meerdere taken als indeling voor meerdere taken.

Taken-API 2.0 en 2.1 ondersteunen nu de updateaanvraag . Gebruik de update aanvraag om een bestaande taak te wijzigen in plaats van de aanvraag opnieuw in te stellen om wijzigingen tussen taken met één taakindeling en taken met meerdere taken te minimaliseren.

API-wijzigingen

De Jobs-API definieert nu een TaskSettings-object voor het vastleggen van instellingen voor elke taak in een baan. Voor taken met meerdere taken wordt het tasks veld, een matrix van TaskSettings gegevensstructuren, opgenomen in het JobSettings-object. Sommige velden die voorheen deel uitmaakten van JobSettings maken nu deel uit van de taakinstellingen voor multitask-formaatopdrachten. JobSettings wordt ook bijgewerkt om het format veld op te nemen. Het format veld geeft de indeling van de taak aan en is een STRING waarde ingesteld op SINGLE_TASK of MULTI_TASK.

U moet uw bestaande API-clients bijwerken voor deze wijzigingen in JobSettings voor multi-task formaat opdrachten. Zie de API-clienthandleiding voor meer informatie over vereiste wijzigingen.

Jobs API 2.1 ondersteunt de indeling voor meerdere taken. Alle API 2.1-aanvragen moeten voldoen aan deze indeling en antwoorden zijn gestructureerd in deze indeling.

Jobs API 2.0 is bijgewerkt met een extra veld om ondersteuning te bieden aan taken in een multitaakformaat. Behalve waar vermeld, gebruiken de voorbeelden in dit document API 2.0. Databricks raadt ECHTER API 2.1 aan voor nieuwe en bestaande API-scripts en -clients.

Een voorbeeld van een JSON-document dat een taak met meerdere taken aangeeft voor API 2.0 en 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"
}

Taken-API 2.1 ondersteunt de configuratie van clusters op taakniveau of een of meer gedeelde taakclusters:

Er wordt een cluster op taakniveau gemaakt en gestart wanneer een taak wordt gestart en beëindigd wanneer de taak is voltooid.
Met een gedeeld taakcluster kunnen meerdere taken in dezelfde taak het cluster gebruiken. Het cluster wordt gemaakt en gestart wanneer de eerste taak die het cluster gebruikt, wordt gestart en beëindigd nadat de laatste taak met behulp van het cluster is voltooid. Een gedeeld taakcluster wordt niet beëindigd wanneer het niet actief is, maar alleen wordt beëindigd nadat alle taken die het gebruiken zijn voltooid. Meerdere niet-afhankelijke taken die een cluster delen, kunnen tegelijkertijd beginnen. Als een gedeeld taakcluster mislukt of wordt beëindigd voordat alle taken zijn voltooid, wordt er een nieuw cluster gemaakt.

Als u gedeelde taakclusters wilt configureren, neemt u een JobCluster matrix op in het JobSettings-object. U kunt maximaal 100 clusters per taak opgeven. Hier volgt een voorbeeld van een API 2.1-antwoord voor een taak die is geconfigureerd met twee gedeelde clusters:

Notitie

Als een taak bibliotheekafhankelijkheden heeft, moet u de bibliotheken configureren in de task veldinstellingen; bibliotheken kunnen niet worden geconfigureerd in een configuratie van een gedeeld taakcluster. In het volgende voorbeeld toont het veld libraries in de configuratie van de ingest_orders taak de specificatie van een bibliotheekafhankelijkheid.

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

Voor taken met één taakindeling blijft de JobSettings gegevensstructuur ongewijzigd, met uitzondering van de toevoeging van het format veld. Er is geen TaskSettings matrix opgenomen en de taakinstellingen blijven gedefinieerd op het hoogste niveau van de JobSettings gegevensstructuur. U hoeft geen wijzigingen aan te brengen in uw bestaande API-clients om taken met één taakindeling te verwerken.

Een voorbeeld van een JSON-document dat een taak met één taakindeling voor API 2.0 vertegenwoordigt:

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

Deze sectie bevat richtlijnen, voorbeelden en vereiste wijzigingen voor API-aanroepen die worden beïnvloed door de nieuwe functie voor indeling met meerdere taken.

In deze sectie:

maken
Uitvoeringen verzenden
Update
opnieuw instellen
Lijst
ophalen
Uitvoeringen worden get
Uitvoeren geven resultaat
Lijst met uitvoeringen

aanmaken

Als u een enkeltaakformaat opdracht wilt maken via de Een nieuwe opdracht maken bewerking (POST /jobs/create) in de Opdracht-API, hoeft u geen bestaande clients te wijzigen.

Als u een taak met meerdere taken wilt maken, gebruikt u het veld tasks in JobSettings om instellingen voor elke taak op te geven. In het volgende voorbeeld wordt een job gemaakt met twee notebooktaken. Dit voorbeeld is voor API 2.0 en 2.1:

Notitie

Er kunnen maximaal 100 taken per taak worden opgegeven.

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

-uitvoeringen verzenden

Als u een eenmalige uitvoering van een taak in enkelvoudig takenformaat wilt verzenden met de bewerking Vervaardigen en activeren van een eenmalige uitvoering (POST /runs/submit) in de Taken-API, hoeft u geen bestaande clients te wijzigen.

Als u een eenmalige uitvoering van een taak met meerdere taken wilt verzenden, gebruikt u het veld tasks in JobSettings om instellingen op te geven voor elke taak, inclusief clusters. Clusters moeten worden ingesteld op taakniveau bij het verzenden van een taakindeling voor meerdere taken, omdat de runs submit aanvraag geen ondersteuning biedt voor gedeelde taakclusters. Zie maken voor een voorbeeld JobSettings het opgeven van meerdere taken.

Bijwerken

Als u een taak met één taakindeling wilt bijwerken met de taakbewerking gedeeltelijk bijwerken (POST /jobs/update) in de Taken-API, hoeft u bestaande clients niet te wijzigen.

Als u de instellingen van een taak met meerdere taken wilt bijwerken, moet u het unieke task_key veld gebruiken om nieuwe task instellingen te identificeren. Zie maken voor een voorbeeld JobSettings het opgeven van meerdere taken.

Terugstellen

Als u de instellingen van een taak met één taak wilt overschrijven met de Alle instellingen voor een taak bewerking (POST /jobs/reset) in de Taken-API overschrijven, hoeft u bestaande clients niet te wijzigen.

Als u de instellingen van een taak met meerdere taken wilt overschrijven, geeft u een JobSettings gegevensstructuur op met een matrix van TaskSettings gegevensstructuren. Zie maken voor een voorbeeld JobSettings het opgeven van meerdere taken.

Gebruik Update om afzonderlijke velden te wijzigen zonder over te schakelen van de indeling met één taak naar de indeling voor meerdere taken.

Lijst

Voor enkel-taakformaat taken zijn er geen clientwijzigingen vereist voor het verwerken van de respons van de bewerking List alle taken (GET /jobs/list) in de Jobs API.

Voor taken met meerdere taken worden de meeste instellingen gedefinieerd op taakniveau en niet op taakniveau. Clusterconfiguratie kan worden ingesteld op taak- of taakniveau. Klanten aanpassen om toegang te krijgen tot cluster- of taakinstellingen voor een multi-taak formaat opdracht die in de Job-structuur wordt geretourneerd.

Parseert het job_id veld voor de taak met meerdere taakindelingen.
Geef de job_id parameter door aan de Get a job-bewerking (GET /jobs/get) in de Jobs-API om taakdetails op te halen. Zie Ophalen voor een voorbeeldantwoord van de Get API-aanroep voor een taak met meerdere taken.

In het volgende voorbeeld ziet u een reactie met een indeling voor enkelvoudige en meervoudige taken. Dit voorbeeld is voor 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"
    }
  ]
}

Toevoegen

Voor taken met één taakindeling zijn er geen clientwijzigingen vereist voor het verwerken van het antwoord van de taakbewerking ophalen (GET /jobs/get) in de Taken-API.

Taken met meerdere taken retourneren een matrix van task gegevensstructuren die taakinstellingen bevatten. Als u toegang nodig hebt tot details op taakniveau, moet u uw clients aanpassen om de tasks matrix te doorlopen en vereiste velden te extraheren.

Hieronder ziet u een voorbeeldantwoord van de Get API-aanroep voor een multitask-formaatopdracht. Dit voorbeeld is voor API 2.0 en 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"
}

Uitvoeringen worden opgehaald

Voor taken in een eenmalige taakindeling zijn er geen wijzigingen in de client vereist om de respons van de Get a job run operatie (GET /jobs/runs/get) in de Jobs API te verwerken.

Het antwoord voor een multi-task format-taak bevat een array van TaskSettings. Uitvoeringsresultaten voor elke taak ophalen:

Doorloop elk van de taken.
Parseer run_id voor elke taak.
Roep de bewerking Haal de uitvoer voor een run op (GET /jobs/runs/get-output) aan met de run_id parameter om details van de uitvoering voor elke taak op te halen. Hier volgt een voorbeeld van een reactie van deze aanvraag:

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

De uitvoeringen genereren uitvoer

Voor taken met één taakindeling zijn er geen clientwijzigingen vereist om het antwoord van de uitvoer ophalen voor een uitvoeringsbewerking (GET /jobs/runs/get-output) in de Taken-API te verwerken.

Voor opdrachten in een multi-taakformaat resulteert het aanroepen van Runs get output op een bovenliggende uitvoering in een fout, omdat de uitvoer alleen beschikbaar is voor afzonderlijke taken. De uitvoer en metagegevens voor een taak met meerdere taken ophalen:

Roep de uitvoer ophalen voor een uitvoeringsaanvraag aan.
Doorloop de run_id subvelden in het antwoord.
Gebruik de waarden van de kindrun_id omRuns get output aan te roepen.

Uitvoeringenlijst

Voor taken met één taakindeling zijn er geen clientwijzigingen vereist voor het verwerken van het antwoord van de lijstuitvoeringen voor een taakbewerking (GET /jobs/runs/list).

Voor multitask-format taken wordt een lege tasks array geretourneerd. Geef de run_id door aan de opdracht Uitvoeren van een taak (GET /jobs/runs/get) om de taken te ontvangen. Hieronder ziet u een voorbeeldantwoord van de Runs list API-aanroep voor een taak met meerdere taken:

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

Feedback

Is deze pagina nuttig?

Last updated on 2026-01-16