Démarrage rapide

Cette page mène à un premier run réussi sur graal Data Platform : obtenir un jeton, créer un projet, envoyer du code, créer un job, le lancer, lire ses logs. Tout passe par l’API — c’est la même que celle qu’utilise la console, il n’y a pas d’API privilégiée réservée à l’interface.

Prérequis : une installation qui répond (voir installation), un compte dans le domaine d’authentification de votre locataire, et le rôle Project Owner ou Tenant Administrator.

0. Les deux en-têtes qui ne changent jamais

Toute requête porte :

Authorization: Bearer <jeton>
X-Tenant: <votre-locataire>

C’est X-Tenant qui choisit le domaine d’authentification, pas l’URL. Une requête sans cet en-tête n’est pas « pour le locataire par défaut » : elle est incomplète.

1. Obtenir un jeton

GRAAL_API=https://app.example.com/api/v1
TENANT=energie-demo

TOKEN=$(curl -s -X POST \
  "https://identity.example.com/realms/$TENANT/protocol/openid-connect/token" \
  -d grant_type=password -d client_id=graal-ui \
  -d "username=$USER_EMAIL" -d "password=$USER_PASSWORD" \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["access_token"])')

Le flux par mot de passe est pratique pour un essai. Pour un usage durable — script, intégration, agent — créez une application et servez-vous de ses identifiants machine plutôt que des vôtres (voir rôles et permissions).

2. Créer un projet

Le type de média porte le nom de la ressource. C’est le premier piège :

curl -s -X POST "$GRAAL_API/projects" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant: $TENANT" \
  -H 'Content-Type: application/vnd.graal.systems.v1.project+json' \
  -d '{"name":"conso-energie","description":"Premier projet"}'

Le type de média est celui du CONTRAT, à la lettre

application/vnd.graal.systems.v1.<type>+json, où <type> est le nom exact de la ressource dans le contrat : instance-type et non instancetype, blobmetadata et non blob-metadata. Une erreur ici ne rend pas un message parlant — elle rend un refus de type de média.

3. Créer l’identité d’exécution

Un job s’exécute sous une identité, qui n’est pas vous.

curl -s -X POST "$GRAAL_API/identities" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant: $TENANT" \
  -H 'Content-Type: application/vnd.graal.systems.v1.identity+json' \
  -d '{"name":"exec-conso","description":"Identité d'"'"'exécution des jobs du projet"}'

Sans identité, la création du job échoue — et mal

identity_id est obligatoire sur un job. Omis, l’appel ne rend pas une erreur de validation lisible mais une erreur serveur. Créez l’identité d’abord.

4. Envoyer le code

Le code d’un job n’est pas collé dans sa définition : il arrive par une bibliothèque. Vous envoyez le fichier, l’API rend une clé, le planificateur le copie dans /workspace avant le démarrage.

cat > premier_job.py <<'PY'
import os
print("bucket :", os.environ.get("GRAAL_BUCKET"))
print("bonjour depuis graal")
PY

KEY=$(curl -s -X POST "$GRAAL_API/libraries" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant: $TENANT" \
  -F file=@premier_job.py \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)[0]["key"])')

5. Créer le job

JOB=$(curl -s -X POST "$GRAAL_API/projects/$PROJECT_ID/jobs" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant: $TENANT" \
  -H 'Content-Type: application/vnd.graal.systems.v1.job+json' \
  -d "{
    \"name\": \"premier-job\",
    \"identity_id\": \"$IDENTITY_ID\",
    \"timeout_seconds\": 900,
    \"max_retries\": 0,
    \"libraries\": [{\"type\": \"file\", \"key\": \"$KEY\"}],
    \"options\": {
      \"type\": \"python\",
      \"file\": \"premier_job.py\",
      \"instance_type\": \"Standard_Development_D1_v1\"
    }
  }" | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')

Ce premier job est de type python. Les autres types (bash, spark, lowcode et les types spécialisés) sont décrits sur la page jobs et workflows.

6. Lancer un run

curl -s -X POST "$GRAAL_API/jobs/$JOB/runs" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant: $TENANT" \
  -H 'Content-Type: application/vnd.graal.systems.v1.run+json' \
  -d "{\"infrastructure_id\": \"$INFRA_ID\"}"

infrastructure_id est obligatoire

Sans lui, l’API répond qu’il faut au moins une infrastructure. Listez celles de votre installation avec GET /infrastructures et prenez-en une.

7. Lire les logs

Les logs sont paginés par curseur, pas par page : vous rappelez avec le curseur rendu par l’appel précédent, et vous obtenez la suite. C’est ce qui permet de suivre un run en direct sans relire depuis le début.

curl -s "$GRAAL_API/jobs/$JOB/runs/$RUN/logs" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant: $TENANT" -D -

L’en-tête X-Cursor de la réponse est à renvoyer dans la requête suivante.

Si rien ne se passe

Un run qui part et n’aboutit jamais, sans message, a presque toujours la même cause : l’URL interne de l’API n’est pas configurée, donc le workload ne peut pas rappeler la plateforme pour signaler son avancement. C’est la panne la plus coûteuse de la liste parce que tous les signaux visibles sont au vert — voir dépannage.

Et ensuite

• Concepts et vocabulaire — si un mot de cette page était flou
• Secrets et bibliothèques — faire lire une base à votre job
• Jobs et workflows — planifier, enchaîner
• API REST — pagination, erreurs, modifications par JSON Patch
• Agents IA (MCP) — faire faire tout ce qui précède par un agent