Les livraisons

La livraison est l'unique moyen pour un utilisateur de déposer de la donnée au sein de la plateforme, et plus précisément au sein de son entrepôt. Une livraison est un espace temporaire de stockage utilisable en entrée d'un traitement. Les fichiers déposés ne sont donc pas faits pour rester dans le temps et ne sont pas utilisables directement par les serveurs de diffusion. Le traitement permet alors de stocker de manière pérenne et utilisable les données pour la diffusion. Une livraison peut également être le résultat de l'exécution d'un traitement.

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

Le contenu d'une livraison est cohérent : on dépose un jeu de données, toutes dans le même système de coordonnées, et sera utilisée dans son intégralité par les traitements. La livraison n'a pas vocation à être utilisée plus tard pour d'autres données, mais d'être supprimée dès que qu'elle a été utilisée par les traitements.

Déclaration d'une nouvelle livraison

Créer un nouvelle livraison se fait via l'appel à POST /datastores/{id}/uploads, en précisant un nom, une description, un type et la projection des données qui y seront déposées. Cela a pour effet de créer une entité upload, avec le statut OPEN.

Le type de la livraison conditionne les types de fichiers de données qui seront attendus et les traitements qui pourront prendre en entrée cette livraison. Rien n'interdit de déposer des données avec des extensions incohérentes avec le type de livraison, mais elles ne seront potentiellement pas prises en compte par les vérifications et les traitements.

Téléversement de fichiers dans la livraison

Le téléversement de fichiers de donnée se fait via l'appel API POST /datastores/{id}/uploads/{id}/data. Il est possible de préciser un sous dossier, afin de créer une arborescence au sein de la livraison.

Il est également possible de déposer des fichiers contenant des signatures MD5 de fichiers téléversés, afin de s'assurer de l'intégrité des données. Chaque ligne de ces fichiers doit avoir le format suivant :

<signature du fichier>  data/<sous chemin de téléversement>/<nom du fichier téléversé>

Si le quota de stockage des livraisons est atteint, le téléversement de fichier n'est plus possible.

Fermeture de la livraison

Lorsque tous les fichiers ont été déposés, on peut demander la fermeture de la livraison via l'appel POST /datastores/{id}/uploads/{id}/close. Cela a plusieurs effets :

• Les accès en écriture à l'arborescence de la livraison ne sont plus possibles
• La livraison passe en statut CLOSED : la livraison peut maintenant être utilisée en entrée d'un traitement ou en sortie.
• Si des vérifications auxquelles l'entrepôt a accès sont configurées pour se lancer automatiquement sur le type de la livraison que l'on ferme, des exécutions de ces vérifications sont lancées et la livraison passe en statut CHECKING. Ce statut n'empêche pas l'utilisation de la livraison en entrée d'un traitement, mais elle ne peut plus être en sortie (pour éviter des conflits entre la vérification d'un contenu et sa modification).

Vérification de la livraison

Une vérification est un script qui effectue des contrôles sur les fichiers téléversés. Ils peuvent être plus ou moins spécifiques, et peuvent être requis par des traitements pour que la livraison puisse être utilisée en entrée. L'objectif est de détecter au plus tôt des erreurs qui feraient échouer les traitements.

Certaines vérifications sont configurées de manière à se lancer automatiquement à la fermeture de livraisons selon leur type. L'utilisateur peut voir les vérifications auxquelles il a accès via l'appel GET /datastores/{id}/checks, avec la possibilité de préciser en paramètre un type de livraison (default_upload_check=[type de livraison]) pour récupérer les vérifications se déclenchant automatiquement sur ce type. Il peut alors en exécuter manuellement sur ses livraisons (CLOSED ou CHECKING), via l'appel POST /datastores/{id}/uploads/{id}/checks. Des vérifications qui auraient déjà été faites (avec succès ou non) ou qui sont en cours sont ignorées.

Il est possible de consulter les exécutions de vérification en cours, en échec et en succès sur une livraison grâce à l'API GET /datastores/{id}/uploads/{id}/checks. Plus globalement, la consultation des exécutions de vérification au sein d'une entrepôt se fait grâce à l'API GET /datastores/{id}/checks/executions. Des filtres, qui se cumulent, permettent de préciser la recherche :

• status=[statut d'exécution de vérification] : permet de préciser le statut voulu. Tous les statuts par défaut.
• check=integer : identifiant de la vérification dont on veut les exécutions.
• after=date : permet de préciser une date limite minimale de lancement des exécutions voulues.
• before=date : permet de préciser une date limite maximale de lancement des exécutions voulues.

Il est également possible d'arrêter une exécution de vérification en cours avec l'API DELETE /datastores/{id}/checks/executions/{id}.

Réouverture de la livraison

Il peut arriver qu'il y ait besoin de modifier le contenu de la livraison : oubli d'un fichier, une vérification en erreur suite à la corruption au transfert du fichier... Cela se fait via l'appel à POST /datastores/{id}/uploads/{id}/open et cela a plusieurs effets :

• On retrouve les accès en écriture (API et FTP) sur l'arborescence de la livraison
• Toutes les exécutions de vérification en succès ou en échec sont oubliées

Cet appel ne peut se faire que sur une livraison en statut CLOSED, en entrée d'aucune exécution de traitement en cours. Les éventuelles exécutions de traitement créées sont supprimées. La livraison repasse alors en statut OPEN.

Utilisation de la livraison par un traitement

Le but premier de la livraison est de servir en entrée d'un traitement pour stocker les données dans un format pérenne et diffusable. Pour cela, on va pouvoir créer une exécution de traitement auquel on a accès (listés ici : GET /datastores/{id}/processings) avec l'appel POST /datastores/{id}/processings/executions. Pour que la création soit acceptée, il faut :

• que le type de la livraison soit accepté par le traitement (GET /datastores/{id}/processings/{id}, si des types sont précisés).
• que la livraison ait passé avec succès les vérifications requises par le traitement
• que le statut de la livraison soit CLOSED, CHECKING ou MODIFYING

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

Génération de la livraison par un traitement

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

Le lancement de l'exécution (POST /datastores/{id}/processings/executions/{id}/launch) change le statut de la livraison en GENERATING. Si l'exécution finit en succès, la livraison passe en statut OPEN, sinon en statut UNSTABLE. Dans ce dernier cas, la réouverture permettra de reprendre la livraison en main.

Modification de la livraison par un traitement

Une livraison en statut CLOSED ou MODIFYING peut être modifiée via une exécution de traitement. Quelque soit la façon dont elle a été créée, on va pouvoir créer une exécution de traitement en précisant l'identifiant de cette livraison en sortie (son type doit être conforme à ce que le traitement permet). Toutes les vérifications que la livraison avait pu connaître sont oubliées.

Le lancement de l'exécution (POST /datastores/{id}/processings/executions/{id}/launch) change le statut de la livraison en MODIFYING (la livraison avait déjà potentiellement ce statut, si d'autres exécutions de traitement avec celle ci en sortie étaient lancées). À la fin de l'exécution (succès, échec ou annulation), la livraison passe en statut OPEN (si plus aucun autre exécution de traitement en cours ne l'a en sortie).

Suppression d'une livraison

Une livraison en statut OPEN, CLOSED 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 /datastores/{id}/uploads/{id}. Cela déclenche l'exécution d'un script qui supprime l'ensemble des fichiers dans l'arborescence de la livraison. La livraison passe en statut DELETED. Elle ne sort alors plus dans les recherches de livraison mais l'entité upload existe toujours, et est toujours accessible via GET /datastores/{id}/uploads/{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 livraison

Il est possible de partager une livraison de son entrepôt avec d'autres entrepôts, via l'appel POST /datastores/{id}/uploads/{id}/sharings. Cela va leur permettre d'utiliser la livraison 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 livraisons partagées apparaissent lors de recherches (GET /datastores/{id}/uploads?shared=true)

Documentation d'une livraison

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

Les étiquettes de livraison

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 livraison sont consultables avec ses informations : GET /datastores/{id}/uploads/{id}
• ajouter des étiquettes se fait via l'API POST /datastores/{id}/uploads/{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 /datastores/{id}/uploads/{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 livraison

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

• consulter les commentaires sur la livraison se fait via GET /datastores/{id}/uploads/{id}/comments
• ajouter un commentaire se fait via POST /datastores/{id}/uploads/{id}/comments, avec le texte du commentaire.
• modifier un commentaire se fait via PUT /datastores/{id}/uploads/{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 /datastores/{id}/uploads/{id}/comments/{id}. Seul l'auteur du commentaire peut le supprimer.

Parcours des livraisons

Récupérer une liste de livraisons

L'API GET /datastores/{id}/uploads permet de récupérer l'ensemble des livraisons (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 livraisons voulues, plusieurs filtres, qui se cumulent, sont possibles :

• owned=booléen : veut-on voir les livraisons appartenant à l'entrepôt. true par défaut.
• shared=booléen : veut-on voir les livraisons publiques ou partagées avec l'entrepôt. false par défaut.
• type=[type de livraison] : permet de préciser le type voulu. Tous les types par défaut.
• status=[statut de livraison] : permet de préciser le statut voulu. Tous les statuts par défaut.
• name=%chaîne% : nom complet ou partiel (% remplace au moins un caractère) des livraisons voulues.

Voir les informations d'une livraison

Pour obtenir toutes les informations disponibles sur une livraison, on utilise l'API GET /datastores/{id}/uploads/{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, les informations d'accès FTP, la taille de la livraison ne sont visibles que pour l'entrepôt propriétaire.

Les événements d'une livraison

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

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