Aller au contenu principal
Dernière mise à jour le

Mise à jour de l'API Jobs 2.1 vers 2.2

Cet article détaille les mises à jour et les améliorations apportées aux fonctionnalités de la version 2.2 de l’API Jobs. Il comprend des informations pour vous aider à mettre à jour vos clients d'API existants afin qu'ils fonctionnent avec cette nouvelle version. Ces mises à jour incluent la mise en file d'attente par **default** des Jobs et un meilleur support pour la *pagination* lorsque les réponses contiennent des champs avec plus de 100 éléments. Parce que la version 2.2 améliore la prise en charge existante de la pagination des grands ensembles de résultats, Databricks vous recommande de l'utiliser pour vos scripts et clients API, en particulier lorsque les réponses peuvent inclure de nombreuses tâches.

Pour en savoir plus sur les changements entre les versions 2.0 et 2.1 de l'API, consultez Mise à jour de l'API Jobs 2.0 vers 2.1.

En plus des modifications incluses dans la version 2,1 de l'API Lakeflow Jobs, la version 2,2 comprend les améliorations suivantes :

Les jobs sont mis en file d'attente par default​

La mise en file d'attente des Jobs est une fonctionnalité facultative qui empêche l'omission d'exécutions de Jobs lorsque les Ressources ne sont pas disponibles pour l'exécution. La mise en file d'attente des Jobs est prise en charge dans les versions 2,0, 2,1 et 2,2 de l'API Jobs, avec les différences suivantes dans la gestion default de la mise en file d'attente :

  • Pour les Jobs créés avec l'API Jobs 2.2, la mise en file d'attente est activée par default. Vous pouvez désactiver la mise en file d'attente en définissant le champ queue sur false dans les corps de requête lorsque vous créez ou mettez à jour un job.
  • Pour les Jobs créés avec les versions 2.0 et 2.1 de l'API Jobs, la mise en file d'attente n'est pas activée par default. Avec ces versions, vous devez activer la mise en file d'attente en définissant le champ queue sur true dans les corps de requête lorsque vous créez ou mettez à jour un Job.

Vous pouvez activer ou désactiver la mise en file d'attente lorsque vous créez un job, mettez à jour partiellement un job ou mettez à jour tous les paramètres de job.

Voir Mise en file d'attente des jobs.

Prise en charge de la pagination des longues listes de tâches et d'exécutions de tâches​

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

L'API Jobs 2.2 modifie la pagination de ces requêtes comme suit :

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

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

JSON
{
  "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 l'ensemble de résultats suivant, définissez le paramètre de query page_token dans la requête suivante sur la valeur renvoyée dans le champ next_page_token. Par exemple, /api/2.2/jobs/get?job_id=11223344&page_token=Z29...E=.

Si aucun autre résultat 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 requêtes list et get.

Modifications des requêtes List jobs et List job runs​

Pour les requêtes List Jobs et List Job Runs, le parameter has_more au niveau racine de l'objet de réponse est supprimé. Au lieu de cela, utilisez 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 les corps de réponse volumineux, les tableaux tasks et job_clusters de niveau supérieur pour chaque job sont omis des réponses par default. Pour inclure ces tableaux pour chaque job inclus dans le corps de la réponse de 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 contient plus de 100 éléments, un champ has_more (à ne pas confondre avec le champ has_more de niveau racine qui est supprimé) à l'intérieur de l'objet job est défini sur true. Cependant, seuls les 100 premiers éléments sont accessibles. Vous ne pouvez pas récupérer de tâches ou de clusters supplémentaires après les 100 premiers avec la requête List jobs. Pour récupérer plus d'éléments, utilisez les requêtes qui retournent un seul Job ou une seule exécution de Job. Les mises à jour qui prennent en charge la pagination des grands champs de réponse sont abordées dans les sections suivantes.

Obtenir un seul job​

Dans l'API Jobs 2.2, la requête Obtenir un Job unique pour récupérer les détails d'un Job unique 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 parameter de query page_token dans les requêtes suivantes. Les champs de tableau contenant moins de 100 éléments sur une page seront vides sur les pages suivantes.

Obtenir une seule exécution​

Dans l'API Jobs 2.2, la requête Obtenir une exécution unique pour récupérer les détails d'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 ultérieures. Les champs de tableau contenant moins de 100 éléments sur une page seront vides sur les pages suivantes.

L'API Jobs 2.2 ajoute également le paramètre de query only_latest à cet Endpoint pour n'afficher que les dernières tentatives d'exécution dans le tableau tasks. Lorsque le parameter only_latest est true, toutes les exécutions remplacées par une nouvelle tentative ou une réparation sont omises de la réponse.

Lorsque le run_id se réfère à 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 de la tâche ForEach et possède les propriétés suivantes :

  • Le schéma de chaque objet dans le tableau iterations est le même que celui des objets dans le tableau tasks.
  • Si le paramètre de requête only_latest est défini sur 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 comprend 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 :

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