Aller au contenu

Documentation Utilisateur - API command

Introduction

L'API command permet l'exécution distante de scripts Lua sur des équipements via un système de tâches (task) et exécutions (job).
Elle permet de déclencher des actions telles que redémarrages, mises à jour, configuration à distance, etc.

Concepts Clés

Task (Tâche)

Une tâche est une commande prête à être exécutée sur des équipements, composée : - D’un nom et d’un script Lua (script) - De variables à fournir à l’exécution (variables_info) - D’options comme des constantes (constants), notifications, ou signature

Exemple : Une tâche demo_cmd qui exécute le script demo_cmd.lua avec une URL et un hash de vérification.

Job (Exécution)

Un job est une exécution concrète d’une tâche sur un device (entity_ident).
Chaque job garde une trace complète de son historique, avec une suite de statuts (ex: pending, running, terminated, etc.).

API Endpoints

Lister les tâches

GET /v3/commands/tasks

Headers 

{
  "api-key": "<votre-api-key>",
  "Content-Type": "application/json"
}

Lire une tâche

GET /v3/commands/tasks/<task_ident>

Créer un job

POST /v3/commands/tasks/<task_ident>/jobs

Body 

{
  "entity_ident": "<uuid_de_la_device>",
  "variables": {
    "url": "https://update.example.com/v1.bin",
    "hash": "9a1b7f..."
  },
  "comment": "Commentaire libre"
}

Lire un job

GET /v3/commands/jobs/<job_ident>

Voir l’historique d’un job

GET /v3/commands/jobs/<job_ident>/history

Planifier un job

Inclure un champ scheduled_time (timestamp Unix) lors de la création du job : 

"scheduled_time": 1750683600

Annuler un job

PATCH /v3/commands/jobs/<job_ident>/cancel

Exemple Complet : Demo CMD

1. Définition de la tâche demo_cmd

{
  "name": "demo_cmd",
  "script": "demo_cmd.lua",
  "variables_info": {
    "firmware_url": {
      "type": "string",
      "alias": "URL"
    },
    "hash": {
      "type": "string",
      "alias": "SHA256"
    }
  },
  "constants": {
    "retry_count": 3
  },
  "allow_offline": true
}

2. Création d’un job associé

{
  "entity_ident": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "variables": {
    "url": "https://update.example.com/v1.2.3.bin",
    "hash": "f87c0f4d5d75a1c8a..."
  },
  "comment": "Update firmware to v1.2.3"
}

3. Lecture du job

{
  "status": "terminated",
  "response": "Job completed successfully."
}

4. Historique typique du job

Statut Description
initial Job créé
pending En file d’attente
edge_transmitted Transmis au device
edge_started Début de l'exécution
edge_running En cours de mise à jour
edge_error Erreur durant l’exécution (si erreur)
terminated Mise à jour terminée

Notifications

L'API permet de configurer des notifications par email pour être alerté à chaque changement d'état d’un job.

Où définir les notifications ?

  • Au niveau de la tâche (task)
    → Les notifications définies ici s’appliqueront à tous les jobs créés à partir de cette tâche.

  • Au niveau du job (job)
    → Ces paramètres sont additionnels à ceux définis dans la tâche.

Les listes sont cumulées. Si une tâche définit une adresse et le job en ajoute une autre, les deux recevront les notifications.

Champs disponibles

Champ Type Description
notification_mail_list Array<String> Emails à notifier
notification_status_list Array<String> Statuts déclencheurs (ex: "terminated", "edge_error")

Exemple d’usage combiné

Dans la tâche :

"notification_mail_list": ["ops@company.com"],
"notification_status_list": ["edge_error", "terminated"]

Dans le job :

"notification_mail_list": ["tech@company.com"],
"notification_status_list": ["edge_error"]

Effet cumulé :

  • Statuts déclencheurs : ["edge_error", "terminated"]
  • Emails notifiés :
  • Lors d’un edge_error → ops@company.com et tech@company.com
  • Lors d’un terminated → ops@company.com uniquement

Comprendre les ident (Identifiants uniques)

Dans l’API command, chaque ressource possède un identifiant universel (UUID) propre à la plateforme ALEMCA.
On les retrouve dans les entités suivantes :

Entité Champ Rôle
Tâche ident Identifie une tâche unique dans le système
Job ident Identifie une exécution particulière d’une tâche
Appareil entity_ident Identifie une device (cible d’un job)
Client Racine client_root Identifie le client maître auquel est lié l’équipement

Remarque : Les identifiants sont uniques, opaques, et ne doivent pas être modifiés ou générés manuellement par l'utilisateur. Ils sont automatiquement assignés par la plateforme.

Exemple anonymisé

{
  "task": {
    "ident": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "demo_cmd"
  },
  "job": {
    "ident": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "entity_ident": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
  }
}

Commandes groupées & Groupes de jobs

L'API command permet de créer des commandes groupées pour exécuter une tâche sur plusieurs devices simultanément.
Ces envois sont organisés sous forme de groupes permettant un suivi centralisé.

Méthodes d'envoi groupé

1. Envoi par liste de devices (ident_list)

POST /v3/commands/tasks/<task_ident>/jobs/list

Body 

{
  "variables": {
    "param1": "valeur",
    "param2": "valeur"
  },
  "comment": "Demo lot 1",
  "group_name": "demo",
  "ident_list": [
    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
  ]
}

2. Envoi par tag

POST /v3/commands/tasks/<task_ident>/jobs/tags

Body 

{
  "variables": {
    "param1": "valeur"
  },
  "comment": "Commandes sur tous les capteurs extérieurs",
  "group_name": "capteurs_ext",
  "tag": "outdoor_sensors"
}

Les jobs seront envoyés à tous les devices possédant le tag spécifié dans l’inventaire ALEMCA.

Groupes

Un groupe est un conteneur logique de jobs liés par un envoi commun (par ident_list ou tag).

  • Un groupe est automatiquement créé si vous spécifiez un group_name.
  • Permet de retrouver tous les jobs exécutés dans le cadre de ce groupe.

Lister les groupes existants

GET /v3/commands/groups

Réponse 

{
  "items": [
    {
      "ident": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "test",
      "created_user": "user@alemca.com"
    },
    ...
  ]
}

Filtrer les jobs d’un groupe

GET /v3/commands/jobs?group_ident=<group_ident>

Réponse 

{
  "items": [
    {
      "task": { "name": "demo_cmd" },
      "group": { "name": "demo" },
      "status": "terminated",
      "entity_ident": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
      "response": "command sent"
    },
    ...
  ]
}

Exemple d’usage

  1. Vous créez une tâche demo_cmd
  2. Vous envoyez un job à 100 devices via /jobs/list avec un group_name
  3. Vous pouvez ensuite :
  4. Suivre chaque job individuellement
  5. Lister tous les jobs avec GET /v3/commands/jobs?group_ident=...

Swagger API Commands

Pour plus d’informations détaillées et la liste complète des endpoints, consultez la documentation Swagger de l'API Commands.