Aller au contenu principal
Dernière mise à jour le

Mise à jour de Jobs API 2.0 vers 2.1

Vous pouvez désormais orchestrer plusieurs tâches avec les jobs Databricks. Cet article détaille les modifications apportées à l'API Jobs qui prennent en charge les jobs avec plusieurs tâches et contient des conseils pour vous aider à mettre à jour vos clients d'API existants afin qu'ils fonctionnent avec cette nouvelle fonctionnalité.

Databricks recommande l'API Jobs 2.1 pour vos scripts et clients API, en particulier lors de l'utilisation de Jobs avec plusieurs tâches.

Cet article désigne les jobs définis avec une seule tâche comme étant au format tâche unique et les jobs définis avec plusieurs tâches comme étant au format multitâches .

Les API Jobs 2.0 et 2.1 prennent désormais en charge la requête update. Utilisez la requête update pour modifier un Job existant au lieu de la requête Reset pour minimiser les changements entre les Jobs au format tâche unique et les Jobs au format multitâche.

Modifications de l'API​

L'API Jobs définit maintenant un objet TaskSettings pour capturer les paramètres de chaque tâche dans un job. Pour les jobs au format multi-tâches, le champ tasks, un tableau de structures de données TaskSettings, est inclus dans l'objet JobSettings. Certains champs précédemment inclus dans JobSettings font maintenant partie des paramètres de tâche pour les jobs au format multi-tâches. JobSettings est également mis à jour pour inclure le champ format. Le champ format indique le format du job 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 aux JobSettings pour les jobs au format multi-tâches. Consultez le guide du client API pour plus d'informations sur les modifications requises.

Jobs API 2.1 prend en charge le format multitâche. Toutes les requêtes API 2.1 doivent être conformes à ce format, et les réponses sont structurées dans ce format.

L'API Jobs 2.0 est mise à jour avec un champ supplémentaire pour prendre en charge les jobs au format multi-tâches. Sauf indication contraire, les exemples de ce document utilisent l'API 2.0. Cependant, Databricks recommande l'API 2.1 pour les scripts et clients API nouveaux et existants.

Exemple de document JSON représentant un Job au format multitâche pour les API 2.0 et 2.1 :

JSON
{
  "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 Jobs 2.1 prend en charge la configuration de clusters au niveau des tâches ou d'un ou plusieurs clusters de Job partagés :

  • Un cluster au niveau de la tâche est créé et starté lorsqu'une tâche start et se termine lorsque la tâche est terminée.
  • Un cluster de Job partagé permet à plusieurs tâches du même job d'utiliser le cluster. Le cluster est créé et start lorsque la première tâche utilisant le cluster start et se termine une fois la dernière tâche utilisant le cluster achevée. Un cluster de job partagé n'est pas arrêté lorsqu'il est inactif, mais seulement une fois que toutes les tâches qui l'utilisent sont terminées. Plusieurs tâches non dépendantes partageant un cluster peuvent start en même temps. Si un cluster de job partagé échoue ou est arrêté avant que toutes les tâches ne soient terminées, un nouveau cluster est créé.

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

remarque

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

JSON
{
  "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 jobs au format tâche unique, 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'aurez pas besoin de modifier vos clients API existants pour traiter les jobs au format tâche unique.

Un exemple de document JSON représentant un job au format de tâche unique pour l'API 2.0 :

JSON
{
  "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 client de l'API​

Cette section fournit des directives, des exemples et les modifications requises pour les appels d'API affectés par la nouvelle fonctionnalité de format multi-tâches.

Dans cette section :

Créer​

Pour créer un job au format tâche unique via l’opération Créer un nouveau job (POST /jobs/create) dans l’API des Jobs, vous n’avez pas besoin de modifier les clients existants.

Pour créer un Job au 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 Job avec deux tâches de Notebook. Cet exemple concerne l'API 2,0 et 2,1 :

remarque

Un maximum de 100 tâches peut être spécifié par Job.

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

Soumission des exécutions​

Pour soumettre une exécution unique d'un Job au format tâche unique avec l'opération Créer et Trigger une exécution unique (POST /runs/submit) dans l'API Jobs, vous n'avez pas besoin de modifier les clients existants.

Pour soumettre une exécution unique d'un job au 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 configurés au niveau de la tâche lors de la soumission d'un job au format multitâche, car la requête runs submit ne prend pas en charge les clusters de job partagés. Voir Create pour un exemple JobSettings spécifiant plusieurs tâches.

Mettre à jour​

Pour mettre à jour un Job au format tâche unique avec l'opération Mettre à jour partiellement un Job (POST /jobs/update) dans l'API Jobs, vous n'avez pas besoin de modifier les clients existants.

Pour mettre à jour les paramètres d'un job au format multi-tâche, vous devez utiliser le champ task_key unique pour identifier les nouveaux paramètres task. Voir Créer pour un exemple JobSettings spécifiant plusieurs tâches.

Reset​

Pour écraser les paramètres d'un job au format tâche unique avec l'opération Écraser tous les paramètres d'un job (POST /jobs/reset) dans l'API Jobs, vous n'avez pas besoin de modifier les clients existants.

Pour remplacer les paramètres d'un job au format multitâche, spécifiez une structure de données JobSettings avec un tableau de structures de données TaskSettings. Voir Créer pour un exemple JobSettings spécifiant plusieurs tâches.

Utilisez Mettre à jour pour modifier des champs individuels sans passer du format tâche unique au format multitâche.

Liste​

Pour les jobs au format tâche unique, aucune modification du client n'est requise pour traiter la réponse de l'opération List all jobs (GET /jobs/list) dans l'API Jobs.

Pour les Jobs au format multi-tâches, la plupart des paramètres sont définis au niveau de la tâche et non au niveau du Job. La configuration du cluster peut être définie au niveau de la tâche ou du Job. Pour modifier les clients afin d'accéder aux paramètres de cluster ou de tâche pour un Job au format multitâche retourné dans la structure Job :

  • Analysez le champ job_id pour le Job au format multitâche.
  • Transmettez le job_id à l’opération Get a job (GET /jobs/get) dans l'API Jobs afin de récupérer les détails du job. Consultez Get pour un exemple de réponse de l'appel d'API Get pour un Job au format multi-tâche.

L'exemple suivant montre une réponse contenant des Jobs au format mono-tâche et multi-tâches. Cet exemple concerne l'API 2.0 :

JSON
{
  "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 les jobs au format tâche unique, aucun changement client n’est requis pour traiter la réponse de l’opération Get a job (GET /jobs/get) dans l’API Jobs.

Les Jobs au format multi-tâches retournent un tableau de task structures de données contenant les paramètres de tâche. Si vous avez besoin d'accéder aux détails au niveau des tâches, vous devez modifier vos clients pour itérer sur le tableau tasks et extraire les champs requis.

Voici un exemple de réponse de l'appel d'API Get pour un job au format multi-tâche. Cet exemple concerne l'API 2,0 et 2,1 :

JSON
{
  "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écutions obtiennent​

Pour les Jobs au format tâche unique, aucune modification client n’est requise pour traiter la réponse de l’opération Obtenir une exécution de Job (GET /jobs/runs/get) dans l’API Jobs.

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

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

Les exécutions produisent des résultats​

Pour les Jobs au format tâche unique, aucune modification côté client n'est requise pour traiter la réponse de l'opération Obtenir la sortie d'une exécution (GET /jobs/runs/get-output) dans l'API Jobs.

Pour les jobs au format multitâche, l'appel de Runs get output sur une exécution parente entraîne une erreur, car la sortie d'exécution n'est disponible que pour les tâches individuelles. Pour obtenir la sortie et les métadonnées d'un job au format multitâche :

Liste des exécutions​

Pour les jobs au format tâche unique, aucune modification du client n'est requise pour traiter la réponse de l'opération Lister les exécutions d'un job (GET /jobs/runs/list).

Pour les Jobs au format multi-tâches, un tableau tasks vide est renvoyé. Transmettez le run_id à l'Obtenir une exécution de Job opération (GET /jobs/runs/get) pour récupérer les tâches. Ce qui suit montre un exemple de réponse de l'appel d'API Runs list pour un Job au format multi-tâches :

JSON
{
  "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
}
Sur cette page