Partager via

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

  • Article

Cet article détaille les mises à jour et les améliorations apportées aux fonctionnalités de la version 2.2 de l’API Travaux. Il inclut des informations pour vous aider à update vos clients API existants à utiliser cette nouvelle version. Ces mises à jour incluent la mise en file d'attente par défaut des tâches et une meilleure gestion de la pagination de lorsque les réponses incluent des champs contenant plus de 100 éléments. Étant donné que la version 2.2 améliore la prise en charge existante de la pagination des jeux de résultats volumineux, Databricks recommande de l’utiliser pour vos scripts et clients d’API, en particulier lorsque les réponses peuvent inclure de nombreuses tâches.

Pour en savoir plus sur les modifications entre les versions 2.0 et 2.1 de l’API, consultez Mise à jour de l’API Travaux 2.0 vers 2.1.

Outre les modifications incluses dans la version 2.1 de l’API Databricks Jobs, la version 2.2 présente les améliorations suivantes :

Les travaux sont mis en file d’attente par défaut

La mise en file d’attente des travaux est une fonctionnalité optionnelle qui empêche les tâches d'être sautées lorsque les ressources ne sont pas disponibles pour leur exécution. La mise en file d’attente des travaux est prise en charge dans les versions 2.0, 2.1 et 2.2 de l’API Travaux, avec les différences suivantes dans la gestion par défaut de la file d’attente :

  • Pour les travaux créés avec l’API Travaux 2.2, la mise en file d’attente est activée par défaut. Vous pouvez désactiver la mise en file d’attente en définissant le champ queue sur false dans les corps de la requête lorsque vous créez ou update un travail.
  • Pour les travaux créés avec les versions 2.0 et 2.1 de l’API Travaux, la mise en file d’attente n’est pas activée par défaut. Avec ces versions, vous devez activer la mise en file d’attente en définissant le champ queue sur true dans les corps de la requête lorsque vous créez ou update une tâche.

Vous pouvez activer ou désactiver la mise en file d’attente lorsque vous créer un travail, partiellement update un travailou update tous les paramètres de travail.

Consultez la mise en file d’attente des travaux .

Prise en charge de la pagination des listes de tâches longues et des listes de tâches exécutées

Pour prendre en charge les travaux avec un grand nombre de tâches ou d’exécutions de tâches, l’API Travaux 2.2 modifie la façon dont les jeux de résultats volumineux sont retournés pour les requêtes suivantes :

L’API Travaux 2.2 modifie la pagination pour ces demandes comme suit :

  • Les champs représentant des listes d’éléments tels que des tâches, des parameters, des job_clusters ou des environnements sont limités à 100 éléments par réponse. Si plus de 100 values sont disponibles, le corps de la réponse inclut un champ next_page_token contenant un jeton pour récupérer la page suivante des résultats.
  • La pagination est ajoutée pour les réponses aux requêtes Get a single job et Get a single job run. La pagination des réponses aux demandes List job et List job runs a été ajoutée avec l’API Jobs 2.1.

Voici un exemple de contenu de la réponse d’une requête de Get a single job pour un travail avec plus de 100 tâches. Pour illustrer la fonctionnalité de pagination basée sur un jeton, cet exemple omet la plupart des champs inclus dans le corps de la réponse :

{
  "job_id": 11223344,
  "settings": {
    "tasks": [
      {
        "task_key": "task-1"
      },
      {
        "task_key": "task-2"
      },
      {
        "task_key": "task-..."
      },
      {
        "task_key": "task-100"
      }
    ]
  },
  "next_page_token": "Z29...E="
}

Pour récupérer la set suivante des résultats, set le paramètre de requête page_token dans la requête suivante à la valeur retournée dans le champ next_page_token. Par exemple, /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Si aucun résultat supplémentaire n’est disponible, le champ next_page_token n’est pas inclus dans la réponse.

Les sections suivantes fournissent plus de détails sur les mises à jour de chacune des demandes de list et de get.

modifications apportées aux demandes de List jobs et de List job runs

Pour les travaux List et les travaux ainsi que les exécutions de travail List et les requêtes, le paramètre has_more au niveau racine de l'objet de réponse est supprimé. Utilisez plutôt l’existence du next_page_token pour déterminer si d’autres résultats sont disponibles. Sinon, la fonctionnalité de pagination des résultats reste inchangée.

Pour éviter des réponses volumineuses, les tableaux de niveau supérieur tasks et job_clusters pour chaque tâche sont omis par défaut des réponses. Pour inclure ces tableaux pour chaque travail inclus dans le corps de la réponse pour ces requêtes, ajoutez le paramètre expand_tasks=true à la requête. Lorsque expand_tasks est activé, un maximum de 100 éléments sont retournés dans les tableaux tasks et job_clusters. Si l’un de ces tableaux comporte plus de 100 éléments, un champ has_more (à ne pas confondre avec le champ de niveau racine has_more supprimé) à l’intérieur de l’objet job est set à true. Toutefois, seuls les 100 premiers éléments sont accessibles. Vous ne pouvez pas récupérer des tâches ou des clusters supplémentaires après les 100 premiers avec les requêtes de Listtravaux . Pour extraire d'autres éléments, utilisez les requêtes qui retournent une seule tâche ou une seule exécution de tâche. Les mises à jour qui prennent en charge la pagination de champs de réponse volumineux sont décrites dans les sections suivantes.

Get un seul travail

Dans l’API Jobs 2.2, Get une demande unique pour récupérer des détails sur un seul travail prend désormais en charge la pagination des champs tasks et job_clusters lorsque l'un ou l'autre des champs dépasse 100 éléments. Utilisez le champ next_page_token à la racine de l’objet pour déterminer si d’autres résultats sont disponibles. La valeur de ce champ est ensuite utilisée comme valeur pour le paramètre de requête page_token dans les requêtes suivantes. Les champs de tableau comportant moins de 100 éléments d’une page sont vides dans les pages suivantes.

Get une seule exécution

Dans l’API Travaux 2.2, la Get une seule exécution demande de récupérer des détails sur une seule exécution prend désormais en charge la pagination des champs tasks et job_clusters lorsque la taille de l’un ou l’autre champ dépasse 100 éléments. Utilisez le champ next_page_token à la racine de l’objet pour déterminer si d’autres résultats sont disponibles. La valeur de ce champ est ensuite utilisée comme valeur pour le paramètre de requête page_token dans les requêtes suivantes. Les champs de tableau comportant moins de 100 éléments d’une page seront vides sur les pages suivantes.

L’API travaux 2.2 ajoute également le paramètre de requête only_latest à ce point de terminaison pour permettre d’afficher uniquement les dernières tentatives d’exécution dans le tableau tasks. Lorsque le paramètre only_latest est true, les exécutions remplacées par une nouvelle tentative ou une réparation sont omises de la réponse.

Lorsque le run_id fait référence à une exécution de tâche ForEach, un champ nommé iterations est présent dans la réponse. Le champ iterations est un tableau contenant les détails de toutes les exécutions de la tâche imbriquée ForEach et possède les propriétés suivantes :

  • La schema de chaque objet du tableau iterations est identique à celle des objets du tableau tasks.
  • Si le paramètre de requête only_latest est set à true, seules les dernières tentatives d’exécution sont incluses dans le tableau iterations.
  • La pagination est appliquée au tableau iterations au lieu du tableau tasks.
  • Le tableau tasks est toujours inclus dans la réponse et inclut l’exécution de la tâche ForEach.

Pour en savoir plus sur la tâche ForEach, consultez la documentation de la tâche ForEach.

Par exemple, consultez la réponse suivante pour une tâche ForEach avec certains champs omis :

{
  "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": "process_all_numbers",
  "run_type": "JOB_RUN",
  "tasks": [
    {
      "run_id": 759600,
      "task_key": "process_all_numbers",
      "description": "Process all numbers",
      "for_each_task": {
        "inputs": "[ 1, 2, ..., 101 ]",
        "concurrency": 10,
        "task": {
          "task_key": "process_number_iteration"
          "notebook_task": {
            "notebook_path": "/Users/user@databricks.com/process_single_number",
            "base_parameters": {
              "number": "{{input}}"
            }
          }
        },
        "stats": {
          "task_run_stats": {
            "total_iterations": 101,
            "scheduled_iterations": 101,
            "active_iterations": 0,
            "failed_iterations": 0,
            "succeeded_iterations": 101,
            "completed_iterations": 101
          }
        }
      }
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "iterations": [
    {
      "run_id": 759601,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    },
    {
      "run_id": 759602,
      "task_key": "process_number_iteration",
      "notebook_task": {
        "notebook_path": "/Users/user@databricks.com/process_single_number",
        "base_parameters": {
          "number": "{{input}}"
        }
      },
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      }
    }
  ],
  "format": "MULTI_TASK",
  "next_page_token": "eyJ..x9"
}