Aller au contenu

Module alemca

Le module alemca permet d'interagir avec le service Alemca. Il est importé via :

Import

local alemca = require("alemca")

Configuration YAML

Le module alemca est chargé par défaut et ne nécessite pas de configuration pour les fonctionnalités de base. La configuration YAML ci-dessous est optionnelle et permet de définir des destinations personnalisées pour la publication de messages :

iot:
  alemca: # configuration de la connexion à alemca
    max_cache_size: 1024 # taille maximum du cache en octets
    destinations: # destinations des messages
      - name: "destination_name" # nom de la destination
        exchange: "destination_name" # nom de l'échange
        routing_key: "destination_name" # clé de routage
        queue_not_durable: false # file non durable
        exchange_type: "direct" # type d'échange

Détails de la configuration

  • max_cache_size : Taille maximum du cache en octets. Si le cache dépasse cette taille, les messages les plus anciens seront supprimés.
  • destinations : Liste des destinations des messages. Chaque destination doit avoir un nom, un échange, une clé de routage, et d'autres options comme la durabilité de la file et le type d'échange.
  • name : Nom de la destination. Utilisé pour identifier la destination dans le code Lua.
  • exchange : Nom de l'échange. Utilisé pour publier des messages.
  • routing_key : Clé de routage. Utilisée pour diriger les messages vers la bonne file d'attente.
  • queue_not_durable : Indique si la file d'attente est non durable. Si true, la file d'attente ne sera pas persistée après un redémarrage.
  • exchange_type : Type d'échange. Peut être direct, fanout, topic, ou headers. Définit comment les messages sont routés vers les files d'attente.

API Lua

Liste des fonctions

Fonction Signature Lua Rôle Retour (succès) Retour (échec)
write bool, err = alemca.write(routingKey, payload [, headers]) Publie immédiatement payload sur la queue routingKey (exchange et routingKey identiques). true, nil nil, "msg"
writebatch bool, err = alemca.writebatch(payload) Ajoute payload au cache disque amqp.cache. true, nil nil, "msg"
sendbatch bool, err = alemca.sendbatch(routingKey [, unique=false [, compress=false [, headers]]]) Vide le cache sur routingKey. unique=true : envoie ligne par ligne. compress=true : gzip. true, nil nil, "msg"
compress compressed, err = alemca.compress(str) Retourne str compressé (gzip + base64). string, nil nil, "msg"
status connected, err = alemca.status() Vérifie la connexion AMQP. true, nil false, "msg"
getbatch len, err = alemca.getbatch() Nombre de lignes dans amqp.cache. n, nil nil, "msg"
clearbatch bool, err = alemca.clearbatch() Purge le cache. true, nil nil, "msg"
read msg, err = alemca.read(queueName) Bloque max 5 s et renvoie le prochain message de queueName. string, nil nil, "msg"
read (ack) msg, tag, err = alemca.read(queueName, true) Lit un message avec accusé de réception différé. string, tag, nil nil, nil, "msg"
ack bool, err = alemca.ack(tag) Accuse réception d’un message précédemment lu. true, nil nil, "msg"
nack bool, err = alemca.nack(tag [, requeue]) Rejette un message, avec ou sans réinjection dans la file. true, nil nil, "msg"
writemetrics err = alemca.writemetrics(metrics [, types [, units [, tags [, ident]]]]) Convertit la table metrics en JSON et l’écrit dans metrics.cache. nil "msg"
pushmetrics err = alemca.pushmetrics() Envoie le contenu de metrics.tmp vers data_metrics_ex. nil "msg"
newcommand bool, err = alemca.newcommand(cmdTable) Planifie l’exécution différée d’un script (Lua) distant. true, nil nil, "msg"
get_entity entity, err = alemca.get_entity([ident]) Récupère l’entité Core. luaTable, nil nil, "msg"
get_children children, err = alemca.get_children([ident]) Récupère les enfants d’une entité. luaTable, nil nil, "msg"
get_attribute attrs, err = alemca.get_attribute([ident]) Récupère les attributs d’une entité. luaTable, nil nil, "msg"
get_config cfg, err = alemca.get_config([ident]) Récupère la configuration d'une entité. luaTable, nil nil, "msg"
write_event bool, err = alemca.write_event(eventTable) Envoie un événement au service Alemca. true, nil nil, "msg"
create_entity json, err = alemca.create_entity(entityTable[, ident]) Crée une nouvelle entité enfant. string, nil nil, "msg"
delete_entity bool, err = alemca.delete_entity([ident]) Supprime une entité. true, nil nil, "msg"
create_attribute bool, err = alemca.create_attribute(ident, name, value) Crée ou met à jour un attribut. true, nil nil, "msg"
delete_attribute bool, err = alemca.delete_attribute(ident, name) Supprime un attribut. true, nil nil, "msg"
create_config bool, err = alemca.create_config([ident,] configTable) Crée ou met à jour la configuration. true, nil nil, "msg"
delete_config bool, err = alemca.delete_config([ident[, configKey]]) Supprime la configuration. true, nil nil, "msg"
Champs alemca.ident, alemca.token, alemca.name, alemca.type Accès direct aux métadonnées chargées. – –

alemca.write(routing_key, message[, headers])

Publie un message à Alemca.

  • Paramètres :
  • routing_key (string) : La clé de routage pour le message. ()
  • message (string) : Le message à envoyer.

  • headers (table, optionnel) : Un tableau contenant des en-têtes supplémentaires pour le message.

  • Retour :

  • true si l'envoi est réussi, sinon retourne une erreur.
local ok, err = alemca.write("uc.raw.temp", '{"t":25.4,"u":"°C"}')
assert(ok, err)

alemca.writebatch(message [, batchName])

Écrit un lot de messages dans le cache. Sépare les messages par des retours à la ligne. Si le cache dépasse la taille maximale, les messages les plus anciens sont supprimés.

  • Paramètres :
  • message (string) : Le message à ajouter au cache.

  • batchName (string, optionnel) : Nom du lot de messages. Si non spécifié, le nom par défaut est utilisé (amq.cache).

  • Retour :

  • true si l'écriture est réussie, sinon retourne une erreur.
alemca.writebatch('{"ts":1680000000,"v":12}')
alemca.writebatch('{"ts":1680000005,"v":13}', "temp_batch.cache")

-- plus tard …
local ok, err = alemca.sendbatch("uc.raw.series", false, true)
assert(ok, err)

alemca.sendbatch(routing_key[, send_mode[, compress_mode[, headers [, batchName]]]])

Envoie un lot de messages à Alemca.

  • Paramètres :
  • routing_key (string) : La clé de routage pour les messages.
  • send_mode (boolean, optionnel) : Si true, tous les messages du cache sont envoyés en un a un ; sinon, ils sont envoyés en une seule fois (séparé par un retour a la ligne) (défaut : false).
  • compress_mode (boolean, optionnel) : Si true, les messages sont compressés avant l'envoi (défaut : false).
  • headers (table, optionnel) : Un tableau d'en-têtes supplémentaires pour les messages.

  • batchName (string, optionnel) : Nom du lot de messages. Si non spécifié, le nom par défaut est utilisé (amq.cache).

  • Retour :

  • true si l'envoi est réussi, sinon retourne une erreur.
alemca.writebatch('{"ts":1680000000,"v":12}')
alemca.writebatch('{"ts":1680000005,"v":13}', "temp_batch.cache")

-- plus tard …
local ok, err = alemca.sendbatch("uc.raw.series", true)
assert(ok, err)

-- plus tard …
local ok, err = alemca.sendbatch("uc.raw.series", false, true, nil, "temp_batch.cache")
assert(ok, err)

alemca.compress(message)

Compresse un message en utilisant l'algorithme GZIP.

  • Paramètres :

  • message (string) : Le message à compresser.

  • Retour :

  • Le message compressé ou une erreur.

alemca.status()

Retourne le statut de la connexion à Alemca.

  • Paramètres : Aucun

  • Retour :

  • true si connecté, sinon retourne une erreur.

alemca.getbatch()

Retourne la longueur du lot de messages en cache.

  • Paramètres : Aucun

  • Retour :

  • La longueur du lot ou une erreur.

alemca.clearbatch()

Efface le lot de messages en cache.

  • Paramètres : Aucun

  • Retour :

  • true si l'effacement est réussi, sinon retourne une erreur.

alemca.read(routing_key[, ack])

Lit un message depuis Alemca.

  • Paramètres :
  • routing_key (string) : La clé de routage du message à lire.

  • ack (boolean, optionnel) : Si true, retourne un tag pour pouvoir "ack" le message après traitement. Si false ou omis, le message est lu sans accusé de réception.

  • Retour :

  • Mode simple : message, nil
  • Mode ack : message, tag, nil
  • Échec : nil, "msg" (ou 3e valeur en mode ack)
local msg, err = alemca.read("alerts")
if msg then
  print("ALERT:", msg)
else
  print("no alert:", err)
end

Mode ack:

local msg, tag, err = alemca.read("alerts", true)
if msg then
  print("ALERT:", msg)
else
  print("no alert:", err)
end

alemca.ack(tag) -- accuse réception du message

alemca.ack(tag)

Accuse réception d'un message précédemment lu.

  • Paramètres :

  • tag (string) : Le tag du message à accuser réception.

  • Retour :

  • status ou une erreur.
local tag = "12345" -- tag obtenu lors de la lecture du message
local ok, err = alemca.ack(tag)
assert(ok, err)

alemca.nack(tag)

Accuse réception d'un message précédemment lu, mais indique qu'il n'a pas été traité correctement.

  • Paramètres :
  • tag (string) : Le tag du message à accuser réception.
  • Retour :
  • status ou une erreur.
local tag = "12345" -- tag obtenu lors de la lecture du message
local ok, err = alemca.nack(tag)
assert(ok, err)

alemca.writemetrics(metrics[, types[, units[, tags[, ident]]]])

Écrit des métriques dans le cache.

  • Paramètres :
  • metrics (table) : Un tableau contenant les métriques.
  • types (table, optionnel) : Un tableau indiquant les types de métriques.
  • units (table, optionnel) : Un tableau indiquant les unités de chaque métrique.
  • tags (table, optionnel) : Un tableau de tags optionnels à inclure.

  • ident (string, optionnel) : L'identifiant à utiliser (par défaut, celui de l'instance Alemca).

  • Retour :

  • true si l'écriture est réussie, sinon retourne une erreur.
alemca.writemetrics(
  {
    { cpu_usage = 75 },
    { memory_usage = 2048 },
    { disk_space = 50000 }
  },
  {
    { cpu_usage = "percent" },
    { memory_usage = "MB" },
    { disk_space = "MB" }
  },
  { 
    cpu_usage = "percent",
    memory_usage = "MB",
    disk_space = "MB"
  },
  { environment = "production", region = "us-west" }
)

alemca.pushmetrics()

Force l'envoie les métriques depuis le cache vers Alemca. Sinon elles sont envoyées automatiquement à intervalle régulier.

  • Paramètres : Aucun

  • Retour :

  • true si l'envoi est réussi, sinon retourne une erreur.

alemca.newcommand(command)

Crée une nouvelle commande pour Alemca.

  • Paramètres :

  • command (table) : Un tableau représentant la commande à exécuter. Les champs requis incluent script, job_ident, variables, constants, attributes, scheduled_time, et expire_time.

  • Retour :

  • true si la commande est créée avec succès, sinon retourne une erreur.
local cmd = {
  script = "reboot.lua",
  job_ident = "reboot-2025-04-30-02h",
  variables = { delay = 10 },
  constants = {},
  attributes = { reason = "nightly-maintenance" },
  scheduled_time = os.time() + 3600,   -- dans 1 h
  expire_time = os.time() + 86400,     -- invalide après 24 h
  cancel = ""
}

local ok, err = alemca.newcommand(cmd)
assert(ok, err)

alemca.get_entity([ident])

Récupère l'entité Core.

  • Paramètres :

  • ident (string, optionnel) : L'identifiant de l'entité à récupérer. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.

  • Retour :

  • Un tableau Lua représentant l'entité.
  • nil et un message d'erreur en cas d'échec.
local entity, err = alemca.get_entity("my_entity")
if entity then
  print("Entity:", entity.name)
else
  print("Error:", err)
end

alemca.get_children([ident])

Récupère les enfants de l'entité Core.

  • Paramètres :

  • ident (string, optionnel) : L'identifiant de l'entité dont on veut récupérer les enfants. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.

  • Retour :

  • Un tableau Lua contenant les enfants de l'entité.
  • nil et un message d'erreur en cas d'échec.
local children, err = alemca.get_children("my_entity")

if children then
  for _, child in ipairs(children) do
    print("Child:", child.name)
  end
else
  print("Error:", err)
end

alemca.get_attribute([ident])

Récupère les attributs de l'entité Core.

  • Paramètres :

  • ident (string, optionnel) : L'identifiant de l'entité dont on veut récupérer les attributs. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.

  • Retour :

  • Un tableau Lua contenant les attributs de l'entité.
  • nil et un message d'erreur en cas d'échec.
local attrs, err = alemca.get_attribute("my_entity")
if attrs then
  for key, value in pairs(attrs) do
    print("Attribute:", key, "=", value)
  end
else
  print("Error:", err)
end

alemca.get_config([ident])

Récupère la configuration de l'entité Core.

  • Paramètres :

  • ident (string, optionnel) : L'identifiant de l'entité dont on veut récupérer la configuration. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.

  • Retour :

  • Un tableau Lua contenant la configuration de l'entité.
  • nil et un message d'erreur en cas d'échec.
local cfg, err = alemca.get_config("my_entity")
if cfg then
  for key, value in pairs(cfg) do
    print("Config:", key, "=", value)
  end
else
  print("Error:", err)
end

alemca.write_event(event_table)

Envoie un événement au service Alemca.

  • Paramètres :

  • event_table (table) : Un tableau Lua contenant les données de l'événement.

  • Retour :

  • true si l'envoi est réussi.
  • nil et un message d'erreur en cas d'échec.
local ok, err = alemca.write_event({
  type = "alert",
  severity = "warning",
  message = "Temperature exceeded threshold",
  value = 85.5
})
assert(ok, err)

alemca.create_entity(entity_table[, parent_ident])

Crée une nouvelle entité enfant dans le service Alemca.

  • Paramètres :
  • entity_table (table) : Un tableau Lua contenant les données de l'entité (name, type, comment, etc.).

  • parent_ident (string, optionnel) : L'identifiant de l'entité parente. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.

  • Retour :

  • Le JSON de l'entité créée en cas de succès.
  • nil et un message d'erreur en cas d'échec.
local result, err = alemca.create_entity({
  name = "Capteur Temperature",
  type = "sensor",
  comment = "Capteur de température salle serveur"
}, "parent_ident")
if result then
  print("Entity created:", result)
else
  print("Error:", err)
end

alemca.delete_entity([ident])

Supprime une entité du service Alemca.

  • Paramètres :

  • ident (string, optionnel) : L'identifiant de l'entité à supprimer. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.

  • Retour :

  • true si la suppression est réussie.
  • nil et un message d'erreur en cas d'échec.
local ok, err = alemca.delete_entity("entity_to_delete")
assert(ok, err)

alemca.create_attribute(ident, attribute_name, value)

Crée ou met à jour un attribut pour une entité dans le service Alemca.

  • Paramètres :
  • ident (string) : L'identifiant de l'entité.
  • attribute_name (string) : Le nom de l'attribut à créer ou mettre à jour.

  • value (any) : La valeur de l'attribut (string, number, boolean, ou table).

  • Retour :

  • true si la création/mise à jour est réussie.
  • nil et un message d'erreur en cas d'échec.
local ok, err = alemca.create_attribute("my_entity", "location", "Salle A")
assert(ok, err)

-- Avec une valeur complexe
local ok, err = alemca.create_attribute("my_entity", "config", {
  threshold = 80,
  unit = "celsius"
})
assert(ok, err)

alemca.delete_attribute(ident, attribute_name)

Supprime un attribut d'une entité dans le service Alemca.

  • Paramètres :
  • ident (string) : L'identifiant de l'entité.

  • attribute_name (string) : Le nom de l'attribut à supprimer.

  • Retour :

  • true si la suppression est réussie.
  • nil et un message d'erreur en cas d'échec.
local ok, err = alemca.delete_attribute("my_entity", "old_attribute")
assert(ok, err)

alemca.create_config([ident,] config_table)

Crée ou met à jour la configuration d'une entité dans le service Alemca.

  • Paramètres :
  • ident (string, optionnel) : L'identifiant de l'entité. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.

  • config_table (table) : Un tableau Lua contenant les données de configuration.

  • Retour :

  • true si la création/mise à jour est réussie.
  • nil et un message d'erreur en cas d'échec.
local ok, err = alemca.create_config("my_entity", {
  polling_interval = 60,
  retry_count = 3,
  enabled = true
})
assert(ok, err)

-- Sans spécifier l'ident (utilise l'ident par défaut)
local ok, err = alemca.create_config({
  polling_interval = 60
})
assert(ok, err)

alemca.delete_config([ident[, config_key]])

Supprime la configuration d'une entité dans le service Alemca.

  • Paramètres :
  • ident (string, optionnel) : L'identifiant de l'entité. Si non spécifié, l'identifiant de l'instance Alemca est utilisé.

  • config_key (string, optionnel) : La clé de configuration à supprimer. Si non spécifié, supprime toute la configuration.

  • Retour :

  • true si la suppression est réussie.
  • nil et un message d'erreur en cas d'échec.
-- Supprimer une clé de configuration spécifique
local ok, err = alemca.delete_config("my_entity", "old_config_key")
assert(ok, err)

-- Supprimer toute la configuration d'une entité
local ok, err = alemca.delete_config("my_entity")
assert(ok, err)

Champs Lua associés

Envoie un événement au service Alemca.

  • Paramètres :

  • eventTable (table) : Un tableau Lua contenant les données de l'événement.

  • Retour :

  • true si l'envoi est réussi, sinon retourne une erreur.
local ok, err = alemca.write_event({
  type = "alert",
  severity = "high",
  message = "Temperature exceeded threshold",
  value = 85.5
})
assert(ok, err)

alemca.create_entity(entityTable[, parentIdent])

Crée une nouvelle entité enfant dans le service Alemca.

  • Paramètres :
  • entityTable (table) : Un tableau Lua contenant les données de l'entité à créer.

  • parentIdent (string, optionnel) : L'identifiant de l'entité parente. Si non spécifié, utilise l'identifiant de l'instance Alemca.

  • Retour :

  • Le JSON de l'entité créée en cas de succès.
  • nil et un message d'erreur en cas d'échec.
local result, err = alemca.create_entity({
  name = "Capteur-01",
  type = "sensor",
  comment = "Capteur de température"
})
if result then
  print("Entité créée : " .. result)
else
  print("Erreur : " .. err)
end

alemca.delete_entity([ident])

Supprime une entité du service Alemca.

  • Paramètres :

  • ident (string, optionnel) : L'identifiant de l'entité à supprimer. Si non spécifié, utilise l'identifiant de l'instance Alemca.

  • Retour :

  • true si la suppression est réussie.
  • nil et un message d'erreur en cas d'échec.
local ok, err = alemca.delete_entity("entity-to-delete")
assert(ok, err)

alemca.create_attribute(ident, attributeName, value)

Crée ou met à jour un attribut pour une entité dans le service Alemca.

  • Paramètres :
  • ident (string) : L'identifiant de l'entité.
  • attributeName (string) : Le nom de l'attribut à créer ou mettre à jour.

  • value (any) : La valeur de l'attribut (peut être string, number, boolean ou table).

  • Retour :

  • true si la création/mise à jour est réussie.
  • nil et un message d'erreur en cas d'échec.
local ok, err = alemca.create_attribute("my_entity", "temperature", 23.5)
assert(ok, err)

-- Avec une table comme valeur
local ok2, err2 = alemca.create_attribute("my_entity", "config", {
  threshold = 30,
  unit = "celsius"
})
assert(ok2, err2)

alemca.delete_attribute(ident, attributeName)

Supprime un attribut d'une entité dans le service Alemca.

  • Paramètres :
  • ident (string) : L'identifiant de l'entité.

  • attributeName (string) : Le nom de l'attribut à supprimer.

  • Retour :

  • true si la suppression est réussie.
  • nil et un message d'erreur en cas d'échec.
local ok, err = alemca.delete_attribute("my_entity", "old_attribute")
assert(ok, err)

alemca.create_config([ident,] configTable)

Crée ou met à jour la configuration d'une entité dans le service Alemca.

  • Paramètres :
  • ident (string, optionnel) : L'identifiant de l'entité. Si non spécifié, utilise l'identifiant de l'instance Alemca.

  • configTable (table) : Un tableau Lua contenant la configuration à créer ou mettre à jour.

  • Retour :

  • true si la création/mise à jour est réussie.
  • nil et un message d'erreur en cas d'échec.
local ok, err = alemca.create_config("my_entity", {
  polling_interval = 60,
  retry_count = 3,
  enabled = true
})
assert(ok, err)

-- Sans ident (utilise l'ident par défaut)
local ok2, err2 = alemca.create_config({
  mode = "active"
})
assert(ok2, err2)

alemca.delete_config([ident[, configKey]])

Supprime la configuration (ou une clé spécifique) d'une entité dans le service Alemca.

  • Paramètres :
  • ident (string, optionnel) : L'identifiant de l'entité. Si non spécifié, utilise l'identifiant de l'instance Alemca.

  • configKey (string, optionnel) : La clé de configuration à supprimer. Si non spécifié, supprime toute la configuration.

  • Retour :

  • true si la suppression est réussie.
  • nil et un message d'erreur en cas d'échec.
-- Supprimer une clé spécifique
local ok, err = alemca.delete_config("my_entity", "polling_interval")
assert(ok, err)

-- Supprimer toute la configuration
local ok2, err2 = alemca.delete_config("my_entity")
assert(ok2, err2)

Champs Lua associés

  • alemca.ident : Retourne l'identifiant de l'instance Alemca.
  • alemca.token : Retourne le token de l'instance Alemca.
  • alemca.name : Retourne le nom de l'instance du module.
  • alemca.type : Retourne le type du module ("alemca").