Partager via

Mise à jour de l’API Travaux 2.0 vers la version 2.1

Vous pouvez désormais orchestrer plusieurs tâches avec les jobs Azure Databricks. Cet article détaille les modifications apportées à l’API Travaux qui prennent en charge les travaux avec plusieurs tâches et fournit des conseils pour vous aider à mettre à jour vos clients API existants pour 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 avec plusieurs tâches.

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

L’API travaux 2.0 et 2.1 prend désormais en charge la demande de mise à jour . Utilisez la update demande pour modifier un travail existant au lieu de la demande de réinitialisation pour réduire les modifications entre les travaux de format à tâche unique et les travaux de format multi-tâche.

Modifications d'API

L’API Travaux définit désormais un TaskSettings objet pour capturer les paramètres de chaque tâche d’un travail. Pour les travaux de format à tâches multiples, 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 tâches au format multi-tâches. JobSettings est également mis à jour pour inclure le format champ. Le format champ indique le format du travail et est une STRING valeur 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 multi-tâches. Pour plus d’informations sur les modifications requises, consultez le guide du client d’API .

L’API Travaux 2.1 prend en charge le format multi-tâches. Toutes les requêtes API 2.1 doivent être conformes à ce format et les réponses sont structurées dans ce format.

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

Exemple de document JSON représentant un travail de format multi-tâches pour 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 des clusters au niveau des tâches ou un ou plusieurs clusters de travaux partagés :

  • Un cluster de niveau tâche est créé et démarré lorsqu’une tâche démarre et se termine une fois la tâche terminée.
  • Un cluster de travaux partagés permet à plusieurs tâches du même travail d’utiliser le cluster. Le cluster est créé et démarré lorsque la première tâche à l’aide du cluster démarre et se termine une fois la dernière tâche effectuée à l’aide du cluster. Un cluster de travaux partagés n’est pas arrêté lorsqu’il est inactif, mais se termine uniquement une fois que toutes les tâches qui l’utilisent sont terminées. Plusieurs tâches non dépendantes partageant un cluster peuvent démarrer en même temps. Si un cluster de travaux partagés échoue ou est arrêté avant la fin de toutes les tâches, un nouveau cluster est créé.

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

Note

Si une tâche a des dépendances de bibliothèque, vous devez configurer les bibliothèques dans les paramètres de task champ ; les bibliothèques ne peuvent pas être configurées dans une configuration de cluster de travaux partagés. Dans l’exemple suivant, le libraries champ de la configuration de la ingest_orders tâche illustre 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 à tâche unique, la JobSettings structure de données reste inchangée, à l’exception de l’ajout du format champ. Aucun tableau n'est inclus TaskSettings, et les paramètres de la tâche restent définis au niveau supérieur de la structure de données JobSettings. Vous n’aurez pas besoin d’apporter des modifications à vos clients API existants pour traiter les travaux de format à tâche unique.

Exemple de document JSON représentant un travail au format tâche unique 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 d’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 multi-tâches.

Dans cette section :

Créer

Pour créer un travail de format à tâche unique 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 pour spécifier les paramètres de chaque tâche dans JobSettings. L’exemple suivant crée un travail avec deux tâches de notebook. Cet exemple concerne l’API 2.0 et la version 2.1 :

Note

Un maximum de 100 tâches peut être spécifié 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
    }
  ]
}

Exécutions d’envoi

Pour soumettre une exécution ponctuelle d’un travail de format à tâche unique avec créer et déclencher une opération d’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 en format multitâche, utilisez le champ tasks dans JobSettings pour 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 multi-tâches, car la runs submit demande ne prend pas en charge les clusters de travaux partagés. Consultez Créer pour obtenir un exemple JobSettings de spécification de plusieurs tâches.

Mettre à jour

Pour mettre à jour un travail au format tâche unique 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 multi-tâches, vous devez utiliser le champ unique task_key pour identifier les nouveaux task paramètres. Consultez Créer pour obtenir un exemple JobSettings de spécification de plusieurs tâches.

Réinitialiser

Pour écraser les paramètres d'un travail au format de tâche unique avec l'opération Écraser tous les paramètres d'un travail dans l'API Travaux, vous n'avez pas besoin de modifier les clients existants.

Pour remplacer les paramètres d’un travail de format multi-tâches, spécifiez une structure de données JobSettings avec un tableau de structures de données TaskSettings. Consultez Créer pour obtenir un exemple JobSettings de spécification de plusieurs tâches.

Utilisez La mise à jour pour modifier des champs individuels sans passer d’une tâche unique à un format à plusieurs tâches.

Liste

Pour les travaux de format à tâche unique, aucune modification du client n’est nécessaire pour traiter la réponse de l’opération Lister toutes les tâches (GET /jobs/list) dans l’API Travaux.

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

  • Analysez le champ job_id pour la tâche au format multi-tâches.
  • Transmettez l’opération job_idObtenir un emploi (GET /jobs/get) dans l’API Emplois pour récupérer les détails de l’emploi. Voir Get pour un exemple de réponse de l’appel Get d’API pour un modèle multi-tâches.

L’exemple suivant montre une réponse contenant des travaux de format à tâche unique et multi-tâches. Cet exemple concerne 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 les travaux de format à tâche unique, aucune modification du client n’est nécessaire pour traiter la réponse à partir de l’opération Obtenir un travail (GET /jobs/get) dans l’API Travaux.

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

Voici un exemple de réponse de l’appel Get d’API pour une tâche au format multi-tâches. Cet exemple concerne l’API 2.0 et la version 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écutions en cours

Pour les travaux de format à tâche unique, aucune modification du client n’est nécessaire pour traiter la réponse à partir de l’opération Get a job run (GET /jobs/runs/get) dans l’API Travaux.

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

  • Effectuez une itération dans chacune des tâches.
  • Analysez le run_id de chaque tâche.
  • Appelez l'opération Obtenir la sortie pour 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 de cette requête :
{
  "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 une sortie

Pour les tâches au format simple, aucune modification du client n’est nécessaire pour traiter la réponse de l’opération Obtenir la sortie pour une exécution (GET /jobs/runs/get-output) dans l’API Jobs.

Pour les travaux de format multi-tâches, l’appel Runs get output sur une exécution parent entraîne une erreur, car la sortie de l’exécution est disponible uniquement pour les tâches individuelles. Pour obtenir la sortie et les métadonnées d’un travail de format multi-tâches :

Liste des exécutions

Pour les travaux de format à tâche unique, aucune modification du client n’est nécessaire pour traiter la réponse des exécutions de liste pour une opération de travail (GET /jobs/runs/list).

Pour les travaux de format multi-tâches, un tableau vide tasks est retourné. Passez le run_id à l'opération Get a job run (GET /jobs/runs/get) pour récupérer les tâches. Voici un exemple de réponse de l’appel Runs list d’API pour un travail de format multi-tâches :

{
  "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
}
  • Last updated on