Plugin Jobs

Déclenchez et surveillez des Databricks Lakeflow Jobs depuis votre application AppKit.

Fonctionnalités clés :

• Prise en charge de plusieurs jobs via des clés de job nommées
• Découverte automatique des jobs à partir des variables d'environnement
• Exécution et attente avec mises à jour de statut diffusées en SSE
• Validation des paramètres via des schémas Zod
• Mappage des paramètres selon le type de tâche (notebook, python_wheel, sql, etc.)

Utilisation de base

import { createApp, server, jobs } from "@databricks/appkit";

await createApp({
  plugins: [server(), jobs()],
});

En l'absence de configuration jobs explicite, le plugin lit DATABRICKS_JOB_ID dans l'environnement et l'enregistre sous la clé default.

Options de configuration

Configuration par job (JobConfig)

Variables d'environnement

Mode job unique

Définissez DATABRICKS_JOB_ID pour exposer un seul job sous la clé default :

DATABRICKS_JOB_ID=123456

const handle = AppKit.jobs("default");

Mode multi-jobs

Définissez DATABRICKS_JOB_<NAME> pour chaque job :

DATABRICKS_JOB_ETL=123456
DATABRICKS_JOB_ML=789012

const etl = AppKit.jobs("etl");
const ml  = AppKit.jobs("ml");

Les noms de variables d'environnement sont en majuscules ; les clés de job, en minuscules. Les jobs détectés dans l'environnement sont fusionnés avec toute configuration jobs explicite — la configuration explicite l'emporte.

Validation des paramètres

Utilisez params pour appliquer un schéma Zod au runtime. Les paramètres non valides sont rejetés avec une erreur 400 avant le déclenchement du job :

import { z } from "zod";

jobs({
  jobs: {
    etl: {
      params: z.object({
        startDate: z.string(),
        endDate: z.string(),
        dryRun: z.boolean().optional(),
      }),
    },
  },
})

Correspondance des types de tâches

Lorsque taskType est défini, le plugin associe automatiquement les paramètres validés aux champs de requête correspondants du SDK :

jobs({
  jobs: {
    etl: {
      taskType: "notebook",
      params: z.object({
        startDate: z.string(),
        endDate: z.string(),
      }),
    },
  },
})

Lorsque taskType est omis, les paramètres sont transmis tels quels au SDK.

Contexte d'exécution

Les jobs s'exécutent toujours sous l'identité du service principal de l'application. Le resource binding de l'application (databricks.yml) accorde CAN_MANAGE_RUN au SP : les utilisateurs peuvent donc déclencher des runs sans grants individuels. Dans l'interface Jobs, l'attribution de chaque run affiche le SP de l'application, et non l'utilisateur humain.

Endpoints HTTP

Toutes les routes sont montées sous /api/jobs.

Déclencher un run

Renvoie { "runId": 12345 }.

Ajoutez ?stream=true pour recevoir des mises à jour de statut via SSE, qui interrogent le service jusqu'à la fin du run :

Chaque événement SSE contient { status, timestamp, run }.

Lister les runs

Renvoie { "runs": [...] }. La limite est ramenée à l'intervalle 1–100, avec 20 par défaut.

Obtenir les détails d'un run

Obtenir le statut le plus récent

Renvoie { "status": "TERMINATED", "run": { ... } } pour le run le plus récent.

Annuler un run

Renvoie 204 No Content en cas de succès.

Accès programmatique

Le plugin exporte une fonction appelable qui sélectionne un job par sa clé :

const AppKit = await createApp({
  plugins: [
    server(),
    jobs({
      jobs: {
        etl: { taskType: "notebook" },
      },
    }),
  ],
});

const etl = AppKit.jobs("etl");

// Déclencher un run
const result = await etl.runNow({ startDate: "2025-01-01" });
if (result.ok) {
  console.log("Run ID:", result.data.run_id);
}

// Déclencher et interroger jusqu'à la fin de l'exécution
for await (const status of etl.runAndWait({ startDate: "2025-01-01" })) {
  console.log(status.status); // "PENDING", "RUNNING", "TERMINATED", etc.
}

// Opérations de lecture
await etl.lastRun();
await etl.listRuns({ limit: 10 });
await etl.getRun(12345);
await etl.getRunOutput(12345);
await etl.getJob();

// Annuler
await etl.cancelRun(12345);

Toutes les méthodes renvoient ExecutionResult<T> — vérifiez result.ok avant d'accéder à result.data.

Valeurs par défaut d'exécution