Mise à jour de l'API Jobs 2.0 vers 2.1

  • Article

Vous pouvez désormais orchestrer plusieurs tâches avec des travaux Azure Databricks. Cet article décrit les modifications apportées à l’API Travaux qui prend en charge des travaux avec plusieurs tâches, et fournit des conseils pour vous aider à mettre à jour vos clients API existants afin qu’ils fonctionnent avec cette nouvelle fonctionnalité.

Databricks recommande l’API Travaux 2.1 pour vos scripts et clients d’API, en particulier lors de l’utilisation de travaux incluant plusieurs tâches.

Cet article fait référence aux travaux définis avec une seule tâche en tant que format monotâche et aux travaux définis avec plusieurs tâches en tant que format multitâche.

Les API Travaux 2.0 et 2.1 prennent désormais en charge la demande update. Utilisez la demande update pour modifier un travail existant au lieu de la demande reset afin de minimiser les modifications entre les travaux de format monotâche et les travaux de format multitâche.

Modifications d'API

L’API Travaux définit désormais un TaskSettings objet pour capturer des paramètres pour chaque tâche dans un travail. Pour les travaux de format multitâche, le champ tasks, un tableau de structures de données TaskSettings, est inclus dans l’objet JobSettings. Certains champs qui faisaient précédemment partie de JobSettings font désormais partie des paramètres de tâche pour les travaux de format multitâche. JobSettings est également mis à jour pour inclure le champ format. Le champ format indique le format du travail et est une valeur STRING définie sur SINGLE_TASK ou MULTI_TASK.

Vous devez mettre à jour vos clients API existants pour ces modifications apportées à JobSettings pour les travaux de format multitâche. Pour plus d’informations sur les modifications requises, consultez le Guide du client API.

L’API Travaux 2.1 prend en charge le format multitâche. Toutes les demandes de l’API 2.1 doivent être conformes au format multitâche et les réponses sont structurées au format multitâche. Les nouvelles fonctionnalités sont publiées d’abord pour l’API 2.1.

L’API Travaux 2.0 est mise à jour avec un champ supplémentaire pour prendre en charge les travaux de format multitâche. Sauf mention contraire, les exemples présentés dans ce document utilisent l’API 2.0. Toutefois, Databricks recommande l’API 2.1 pour les scripts et clients API nouveaux et existants.

Exemple de document JSON représentant un travail de format multitâche pour les API 2.0 et 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"
}

L’API Travaux 2.1 prend en charge la configuration de clusters de niveau tâche ou d’un ou plusieurs clusters de travail partagé :

  • Un cluster de niveau tâche est créé et démarré quand une tâche démarre, et s’arrête quand la tâche se termine.
  • Un cluster de travail partagé permet que plusieurs tâches dans le même travail utilisent le cluster. Le cluster est créé et démarré lorsque la première tâche utilisant le cluster démarre, et se termine après la fin de la dernière tâche utilisant le cluster. Un cluster de travail partagé ne s’arrête pas quand il est inactif, mais uniquement une fois que toutes les tâches qui l’utilisent sont terminées. Plusieurs tâches non dépendantes qui partagent un cluster peuvent démarrer en même temps. Si un cluster de travail partagé échoue ou s’arrête avant que toutes les tâches soient terminées, un nouveau cluster est créé.

Pour configurer des clusters de travail partagé, incluez un tableau JobCluster dans l’objet JobSettings. Vous pouvez spécifier un maximum de 100 clusters par travail. Voici un exemple de réponse de l’API 2.1 pour un travail configuré avec deux clusters partagés :

Notes

Si une tâche a des dépendances de bibliothèque, vous devez configurer les bibliothèques dans les paramètres du champ task. Des bibliothèques ne peuvent pas être configurées dans une configuration de cluster de travail partagé. Dans l’exemple suivant, le champ libraries dans la configuration de la tâche ingest_orders montre la spécification d’une dépendance de bibliothèque.

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

Pour les travaux de format monotâche, la structure de données JobSettings reste inchangée, à l’exception de l’ajout du champ format. Aucun tableau TaskSettings n’est inclus, et les paramètres de tâche restent définis au niveau supérieur de la structure de données JobSettings. Vous n’avez pas besoin d’apporter des modifications à vos clients API existants pour traiter les travaux de format monotâche.

Exemple de document JSON représentant un travail de format multitâche pour l’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"
}

Guide du client API

Cette section fournit des instructions, des exemples et des modifications requises pour les appels d’API affectés par la nouvelle fonctionnalité de format multitâche.

Dans cette section :

Créer

Pour créer un travail de format monotâche via l’opération Créer un travail ( POST /jobs/create ) dans l’API Travaux, vous n’avez pas besoin de modifier les clients existants.

Pour créer un travail de format multitâche, utilisez le champ tasks dans JobSettings pour spécifier les paramètres de chaque tâche. L’exemple suivant crée un travail avec deux tâches de notebook. Cet exemple a trait aux API 2.0 et 2.1 :

Notes

Vous pouvez spécifier au maximum 100 tâches par travail.

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

Envoyer les exécutions

Pour soumettre une exécution ponctuelle d’un travail de format monotâche avec l’opération Créer et déclencher une exécution unique (POST /runs/submit) dans l’API Travaux, vous n’avez pas besoin de modifier les clients existants.

Pour soumettre une exécution ponctuelle d’un travail de format multitâche, utilisez le champ tasks dans JobSettings afin de spécifier les paramètres de chaque tâche, y compris les clusters. Les clusters doivent être définis au niveau de la tâche lors de l’envoi d’un travail de format multitâche, car la demande runs submit ne prend pas en charge les clusters de travail partagé. Pour obtenir un exemple JobSettings spécifiant plusieurs tâches, consultez Créer.

Mises à jour

Pour mettre à jour un travail de format monotâche avec l’opération Mettre à jour partiellement un travail (POST /jobs/update) dans l’API Travaux, vous n’avez pas besoin de modifier les clients existants.

Pour mettre à jour les paramètres d’un travail de format multitâche, vous devez utiliser le champ unique task_key afin d’identifier les nouveaux paramètres task. Pour obtenir un exemple JobSettings spécifiant plusieurs tâches, consultez Créer.

R

Pour remplacer les paramètres d’un travail de format monotâche par l’opération Remplacer tous les paramètres pour un travail (POST /jobs/reset) dans l’API Travaux, vous n’avez pas besoin de modifier les clients existants.

Pour remplacer les paramètres d’un travail de format multitâche, spécifiez une structure de données JobSettings avec un tableau de structures de données TaskSettings. Pour obtenir un exemple JobSettings spécifiant plusieurs tâches, consultez Créer.

Utilisez Mettre à jour pour modifier des champs individuels sans passer d’un format monotâche à un format multitâche.

Liste

Pour des travaux de format monotâche, aucune modification de client n’est requise pour traiter la réponse de l’opération Répertorier tous les travaux (GET /jobs/list) dans l’API Travaux.

Pour les travaux de format multitâche, la plupart des paramètres sont définis au niveau de la tâche, non au niveau du travail. La configuration du cluster peut être définie au niveau de la tâche ou du travail. Pour modifier des clients afin qu’ils puissent accéder aux paramètres de cluster ou de tâche pour un travail de format multitâche retourné dans la structure Job :

  • Analysez le champ job_id pour le travail de format multitâche.
  • Transmettez le job_id à l’opération Obtenir un travail (GET /jobs/get) dans l’API Travaux pour récupérer les détails du travail. Pour voir un exemple de réponse de l’appel d’API Get pour un travail de format multitâche, consultez Get.

L’exemple suivant montre une réponse contenant des travaux de format monotâche et multitâche. Cet exemple a trait à l’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"
    }
  ]
}

Obtenir

Pour des travaux de format monotâche, aucune modification de client n’est requise pour traiter la réponse de l’opération Obtenir un travail (GET /jobs/get) dans l’API Travaux.

Les travaux de format multitâche retournent un tableau de structures de données task contenant des paramètres de tâche. Si vous avez besoin d’accéder à des détails au niveau de la tâche, vous devez modifier vos clients pour qu’ils effectuent une itération au sein du tableau tasks et extraient les champs requis.

Vous trouverez ci-après un exemple de réponse de l’appel d’API Get pour un travail de format multitâche. Cet exemple a trait aux API 2.0 et 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"
}

Exécute get

Pour des travaux de format monotâche, aucune modification de client n’est requise pour traiter la réponse de l’opération Obtenir une exécution de travail (GET /jobs/runs/get) dans l’API Travaux.

La réponse pour une exécution de travail de format multitâche contient un tableau de TaskSettings. Pour récupérer les résultats de l’exécution de chaque tâche :

  • Effectuez une itération dans chacune des tâches.
  • Analysez run_id pour chaque tâche.
  • Appelez l’opération Obtenir la sortie pour une exécution (GET /jobs/runs/get-output) avec run_id pour obtenir des détails sur l’exécution de chaque tâche. Voici un exemple de réponse de cette demande :
{
  "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"
}

Exécute get output

Pour des travaux de format monotâche, aucune modification de client n’est requise pour traiter la réponse de l’opération Obtenir la sortie pour une exécution (GET /jobs/runs/get-output) dans l’API Travaux.

Pour les travaux de format multitâche, l’appel de Runs get output sur une exécution parente aboutit à une erreur, car la sortie de l’exécution est disponible uniquement pour des tâches individuelles. Pour obtenir la sortie et les métadonnées d’un travail de format multitâche :

  • Appelez la demande Obtenir la sortie pour une exécution.
  • Effectuez une itération sur les champs run_id enfants dans la réponse.
  • Utilisez les valeurs run_id enfants pour appeler Runs get output.

Exécute list

Pour des travaux de format monotâche, aucune modification de client n’est requise pour traiter la réponse de l’opération Afficher la liste des exécutions pour un travail (GET /jobs/runs/list).

Pour les travaux de format multitâche, un tableau tasks vide est retourné. Transmettez le run_id à l’opération Obtenir une exécution de travail (GET /jobs/runs/get) pour récupérer les tâches. Vous trouverez ci-après un exemple de réponse de l’appel d’API Runs list pour un travail de format multitâche :

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