Partager via

Mise à jour de l’API Travaux 2.1 vers la version 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 Travaux. Il inclut des informations pour vous aider à mettre à jour vos clients API existants pour qu’ils fonctionnent avec 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 Lakeflow 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 des requêtes lorsque vous créez ou mettez à jour une tâche.
  • 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 requête lorsque vous créez ou mettez à jour une tâche.

Vous pouvez activer ou désactiver la file d’attente lorsque vous créez un travail, mettez partiellement à jour un travail ou mettez à jour 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 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 next_page_token champ 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 le jeu de résultats suivant, définissez le page_token paramètre de requête dans la requête suivante sur la valeur retournée dans le next_page_token champ. 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 requêtes Lister les travaux et Lister les exécutions de travaux, le paramètre has_more au niveau racine de l'objet 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 has_more champ (à ne pas confondre avec le champ de niveau has_more racine supprimé) à l’intérieur de l’objet job est défini true. sur 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 premières demandes de travaux de liste . 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.

Obtenir un emploi unique

Dans l'API Emplois 2.2, la requête Get a single job pour récupérer les détails d'un emploi 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 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.

Effectuer une seule exécution

Dans l’API Travaux 2.2, la requête Obtenir une seule exécution pour récupérer des détails sur une seule exécution prend désormais en charge la pagination des champs et des tasks champs lorsque la taille de l’un ou job_clusters 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 iterations champ est un tableau contenant des détails pour toutes les exécutions de la ForEach tâche imbriquée et possède les propriétés suivantes :

  • Le schéma de chaque objet du iterations tableau est identique à celui des objets du tasks tableau.
  • Si le paramètre de requête only_latest est défini sur true, seules les tentatives d'exécution les plus récentes 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"
}
  • Last updated on