Les données stockées

Les données stockées sont les entités centrales de la plateforme et d'un entrepôt. Elles correspondent aux données stockées de manière durable, dans un format exploitable par les serveurs de diffusion.

Les données stockées ne sont pas directement créées par l'utilisateur, mais sont le résultat d'un traitement. Elles sont également une source de données pour les traitements, permettant ainsi leur modification, dérivation, optimisation.

D'un point de vue modèle, une stored_data appartient à un datastore.

Les types de données stockées

Le type de la donnée stockée préfigure de la diffusion que l'on va pouvoir faire de la donnée.

Utilisation de la donnée stockée en entrée d'un traitement

Même si l'objectif principal d'une donnée stockée est d'être diffusée, elle peut également servir en entrée d'un traitement. On va pouvoir créer une exécution de traitement auquel on a accès (listés ici : GET /datastore/{id}/processings) avec l'appel POST /datastore/{id}/processings/executions. Pour que la création soit acceptée, il faut :

• que le type de la donnée stockée soit accepté par le traitement (GET /datastore/{id}/processings/{id})
• que le statut de la donnée stockée soit GENERATED ou MODIFYING.

À ce stade, la donnée stockée n'est pas bloquée. On peut toujours supprimer la donnée stockée, ce qui aura pour effet de supprimer les exécutions de traitement dont elle est en entrée. Seul le lancement de l'exécution verrouille la donnée stockée et empêche ces actions.

Génération de la donnée stockée par un traitement

Une donnée stockée doit être créée via une exécution de traitement. On crée une exécution d'un traitement ayant en sortie un type de donnée stockée avec l'appel POST /datastore/{id}/processings/executions, en précisant un nom de donnée en sortie. La création de cette exécution va entraîner la création de la donnée stockée en statut CREATED, typée comme précisé par le traitement. Si l'exécution n'est pas lancée mais supprimée (DELETE /datastore/{id}/processings/executions/{id}), la donnée stockée est complètement supprimée (l'entité stored_data n'existe plus).

Le lancement de l'exécution (POST /datastore/{id}/processings/executions/{id}/order?order=launch) change le statut de la donnée stockée en GENERATING. Si l'exécution finit en succès, la donnée stockée passe en statut GENERATED, sinon en statut UNSTABLE. Dans ce dernier cas, seule la suppression sera possible.

Modification de la donnée stockée par un traitement

Il est possible de modifier le contenu d'une donnée stockée existante en la précisant en sortie d'une exécution de traitement via son identifiant. Son statut doit alors être GENERATED ou MODIFYING. Son type doit également être conforme à ce que le traitement attend. La création de cette exécution ne va pas changer le statut de la donnée stockée.

Le lancement de l'exécution (POST /datastore/{id}/processings/executions/{id}/order?order=launch) va passer le statut de la donnée stockée à MODIFYING. Que l'exécution finisse en succès ou en échec, ou que l'exécution soit arrêtée, la donnée stockée repasse en statut GENERATED (le traitement gère la remise en état suite à une erreur rencontrée).

Suppression d'une donnée stockée

Une donnée stockée en statut GENERATED ou UNSTABLE qui n'est pas en entrée d'une exécution de traitement lancée peut être supprimée via l'appel DELETE /datastore/{id}/stored_data/{id}. Cela déclenche l'exécution d'un script qui supprime l'ensemble des fichiers, objets ou tables sur les espaces de stockage. Cette action peut prendre du temps, mais la donnée stockée passe directement en DELETED : elle ne sort alors plus dans les recherches de donnée stockée mais l'entité stored_data existe toujours, et est toujours accessible via GET /datastore/{id}/stored_data/{id}. Elle n'est plus utilisable mais on garde les informations sur elle dans un souci d'historisation (retrouver la source d'une donnée stockée par exemple).

Partage d'une donnée stockée

Il est possible de partager une donnée stockée de son entrepôt avec d'autres entrepôt, via l'appel POST /datastore/{id}/stored_data/{id}/sharings. Cela va leur permettre d'utiliser la donnée en entrée de leurs exécutions de traitement. Les entrepôts avec lesquels le partage a été fait peuvent accéder à quelques informations de découverte (moins que l'entrepôt propriétaire). De plus, il est possible de demander explicitement à ce que les données stockées partagées apparaissent lors de recherches (GET /datastore/{id}/stored_data?shared=true)

Documentation d'une donnée stockée

Il y a deux possibilités pour ajouter des informations sur une donnée stockée : les étiquettes et les commentaires.

Les étiquettes de donnée stockée

Une étiquette est un couple clé - valeur. Il y a une liberté complète sur les clés utilisables (dans la limite d'une taille de 64 caractère) et les valeurs (dans la limite d'une taille de 128 caractère) :

• les étiquettes d'une donnée stockée sont consultables avec ses informations : GET /datastore/{id}/stored_data/{id}
• ajouter des étiquettes se fait via l'API POST /datastore/{id}/stored_data/{id}/tags. Si une étiquette à ajouter reprend une clé déjà présente, la valeur est mise à jour.
• supprimer des étiquettes se fait via l'API DELETE /datastore/{id}/stored_data/{id}/tags?tags=[liste des clés à supprimer]. Si une clé à supprimer n'existe pas, il n'y a pas d'erreur.

Les commentaires de donnée stockée

Les commentaires permettent d'ajouter des détails sur les données et d'avoir une discussion autour de la donnée stockée. Un commentaire est une entité avec identifiant, dont l'auteur du commentaire est connu :

• consulter les commentaires sur la donnée stockée se fait via GET /datastore/{id}/stored_data/{id}/comments
• ajouter un commentaire se fait via POST /datastore/{id}/stored_data/{id}/comments, avec le texte du commentaire.
• modifier un commentaire se fait via PUT /datastore/{id}/stored_data/{id}/comments/{id}, avec le nouveau texte du commentaire. La date de la modification est enregistrée. Seul l'auteur du commentaire peut le modifier.
• supprimer un commentaire se fait via DELETE /datastore/{id}/stored_data/{id}/comments/{id}. Seul l'auteur du commentaire peut le supprimer.

Les événements d'une données stockée

Les événements permettent de mémoriser les actions ayant été faites sur une donnée stockée, avec une datation. Ils sont accessibles via l'appel GET /datastore/{id}/stored_data/{id}/events et peuvent être les suivants :

Les transitions entre les différents statuts sont détaillées ici

Parcours des données stockées

Récupérer une liste de données stockées

L'API GET /datastore/{id}/stored_data permet de récupérer l'ensemble des données stockées (avec pagination) disponibles dans l'entrepôt : celles appartenant à l'entrepôt, celles partagées avec et celles publiques. Pour cibler plus précisément les données stockées voulues, plusieurs filtres, qui se cumulent, sont possibles :

• owned=booléen : veut-on voir les données stockées appartenant à l'entrepôt. true par défaut.
• shared=booléen : veut-on voir les données stockées publiques ou partagées avec l'entrepôt. false par défaut.
• type=[type de donnée stockée] : permet de préciser le type voulu. Tous les types par défaut.
• tags=clé1:valeur1;clé2:valeur2 : liste les étiquettes exacte (clé+valeur) des données stockées voulues.
• name=%chaîne% : nom complet ou partiel (% remplace au moins un caractère) des données stockées voulues.
• status=[statut de donnée stockée] : permet de préciser le statut voulu. Tous les statuts par défaut.

Voir les informations d'une donnée stockée

Pour obtenir toutes les informations disponibles sur une donnée stockée, on utilise l'API GET /datastore/{id}/stored_data/{id}. Selon que l'entrepôt est propriétaire ou seulement en partage, les informations retournées ne seront pas les mêmes. Les commentaires, les étiquettes, le statut, le type de stockage, la taille de la donnée stockée ne sont visibles que pour l'entrepôt propriétaire.