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 ondersteuning bieden voor taken met meerdere taken en richtlijnen biedt voor het bijwerken van uw bestaande API-clients 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 update aanvraag. 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 taken met meerdere taken. 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
- bijwerken
- opnieuw instellen
- lijst
- ophalen
- uitvoeringen worden
- uitvoeringen krijgen uitvoer
- 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 met 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 Een taak gedeeltelijk bijwerken bewerking (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.
opnieuw instellen
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 bijwerken om afzonderlijke velden te wijzigen zonder over te schakelen van één taak naar indeling voor meerdere taken.
Lijst
Voor taken met één taakindeling zijn er geen clientwijzigingen vereist om het antwoord van de Alle taken bewerking (GET /jobs/list) in de Taken-API te verwerken.
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_idveld voor de taak met meerdere taakindelingen. - Geef de
job_iddoor aan de Een taak -bewerking (GET /jobs/get) ophalen in de taken-API om taakdetails op te halen. Zie Get voor een voorbeeldantwoord van deGetAPI-aanroep voor een taak in multitakenformaat.
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"
}
]
}
Ophalen
Voor taken met één taakindeling zijn er geen clientwijzigingen vereist om het antwoord van de Een taak ophalen bewerking (GET /jobs/get) in de Taken-API te verwerken.
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 krijgen
Voor taken in een enkel taakformaat zijn er geen wijzigingen aan de client vereist om de respons van de Taakuitvoering (GET /jobs/runs/get) in de Taken-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_idvoor elke taak. - Roep aan om de uitvoer van een run-bewerking (
GET /jobs/runs/get-output) op te halen metrun_idvoor details over de uitvoering per taak. 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"
}
Uitvoeringen krijgen uitvoer
Voor taken met één taakindeling zijn er geen clientwijzigingen vereist om het antwoord van de De uitvoer ophalen voor een-bewerking (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. Om de uitvoer en metagegevens voor een multitask-formaattaak te verkrijgen:
- Roep de uitvoer op voor een runverzoek via
. - Doorloop de
run_idsubvelden in het antwoord. - Gebruik de waarden van het kind
run_idomRuns get outputaan te roepen.
lijst met uitvoeringen van
Voor taken met één taakindeling zijn er geen clientwijzigingen vereist voor het verwerken van het antwoord van de Lijstuitvoeringen voor een taak bewerking (GET /jobs/runs/list).
Voor multitask-format taken wordt een lege tasks array geretourneerd. Geef de run_id door aan de om de taakuitvoeringsoperatie (GET /jobs/runs/get) uit te voeren en de taken op te halen. 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
}