Maintenir les données à jour

La plateforme OpenDataSoft permet, au sein d’un même catalogue de données, de gérer des jeux de données entièrement statiques (qui n’ont besoin d’être publiés qu’une seule fois) et des jeux de données en temps réel (qui doivent être régulièrement mis à jour). Vous disposez de deux mécanismes pour gérer l’actualisation des jeux de données.

Le premier est appelé planification et consiste à republier automatiquement un jeu de données à intervalles réguliers. Ce mode se révèle particulièrement utile pour les jeux de données dotés d’une ressource distante régulièrement mise à jour.

Le second consiste à pousser les données sur la plateforme OpenDataSoft par l’intermédiaire du point d’entrée d’une API dédiée. Ce mode se révèle particulièrement utile lorsque les données peuvent être directement envoyées par le système produisant les points de données, par exemple un logiciel qui envoie des métriques d’événement ou un ensemble de sondes qui envoie ses mesures.

Utiliser la planification pour maintenir un jeu de données à jour

Cette solution est la plus facile à mettre en œuvre, elle ne nécessite aucun développement, seulement une source distante et quelques paramètres dans la configuration du jeu de données.

Spécifier une ressource

resource interface

Afin de pouvoir utiliser la planification d’un jeu de données, la ressource dont il dépend doit être distante, spécifiée sous la forme d’une URL (les protocoles http et ftp sont utilisables) et non d’un fichier téléchargé. Pour ajouter une ressource distante, collez simplement une URL dans le champ URL.

Spécifier un intervalle de planification

scheduling tab

Une fois qu’un jeu de données est enregistré et qu’il dispose d’une ressource distante, l’onglet planification est activé. L’intervalle minimum est d’une minute, mais il n’est pas activé par défaut. Veuillez contacter l’assistance OpenDataSoft si vous avez besoin d’une planification à des intervalles précis à la minute sur votre domaine. Vous pouvez ajouter autant de planifications que vous le souhaitez. Par exemple, si nécessaire, vous pouvez décider de planifier le retraitement d’un jeu de données chaque lundi matin et chaque mercredi après-midi.

Pousser des données en temps réel

Pour certains types de données, il peut être utile de pousser les données au lieu de les extraire, comme c’est le cas traditionnellement, depuis une ressource via la plateforme. Pour répondre à ce besoin, la plateforme OpenDataSoft propose une API Push (pousser) en temps réel. Elle ne doit pas être confondue avec la capacité à planifier le traitement d’un jeu de données. Avec la planification, le jeu de données extrait périodiquement la ressource et traite les données qu’elle contient, tandis qu’avec l’API Push, le jeu de données est alimenté par une application via une API Push, et les enregistrements sont traités un par un dès leur réception.

Note

Cette fonctionnalité étant actuellement en version bêta, elle n’est pas activée par défaut. Veuillez contacter l’assistance OpenDataSoft si vous souhaitez l’essayer.

Configurer le schéma du jeu de données

source dropdown

Pour créer un jeu de données en temps réel, accédez tout d’abord à l’interface de création de jeux de données. De là, sélectionnez “Ajouter une source en temps réel”.

realtime resource pane

Il vous sera demandé de saisir les données d’amorçage et, éventuellement, de renseigner des options supplémentaires. Les données d’amorçage doivent contenir tous les champs qui seront envoyés via l’API. Veuillez noter que les données d’amorçage ne sont pas utilisées dans le jeu de données : elles ont pour seule fonction de permettre la configuration du jeu de données.

Utiliser l’URL Push

push url in the realtime resource

Une fois votre jeu de données enregistré avec les paramètres de ressource en temps réel corrects, un chemin d’URL contenant la clé d’API s’affiche. Ce chemin, qui vient s’ajouter à l’URL de base de votre domaine, indique l’adresse à laquelle la plateforme attendra les données après leur publication. Tout comme pour les données d’amorçage, les données doivent être envoyées au format JSON, soit sous la forme d’un objet JSON pour un enregistrement simple, soit sous la forme d’un tableau JSON pour pousser plusieurs enregistrements simultanément.

table view with a single record with value "Hello World!" in the "message" field

Voici un exemple simple d’utilisation de l’API avec la commande curl pour un jeu de données présentant un seul champ nommé “message”

curl -XPOST <DOMAIN_URL>/api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/push/?pushkey=<PUSH_API_KEY> -d'{"message":"Hello World!"}'

Voici un autre exemple avec le même jeu de données, qui utilise cette fois un tableau pour envoyer plusieurs enregistrements simultanément

curl -XPOST <DOMAIN_URL>/api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/push/?pushkey=<PUSH_API_KEY> -d'[{"message":"¡Hola Mundo!"},{"message":"Hallo Welt!"}]'

Si les enregistrements ont été correctement reçus, le serveur répond alors avec le message suivant.

{
    "status": "OK"
}

Si une erreur se produit lorsque vous essayez de pousser un enregistrement, la réponse indiquera l’erreur.

Pousser un champ de type de fichier

Afin de pousser un champ de type image, un objet JSON contenant les données encodées en Base64 et le type de mime du fichier doit être envoyé, comme suit.

{
    "image_field": {
        "content": "BASE64 data",
        "content-type": "image/jpg"
    }
}

Mettre à jour les données en définissant une clé unique

table view with 2 records containing respectively 978-0060589462 and 978-2862744506 as isbn and 3 and 5 as number_of_copies

Parfois, il peut être utile de mettre à jour les enregistrements existants plutôt que d’en pousser de nouveaux. Prenons par exemple le cas d’un jeu de données ayant pour fonction de surveiller le nombre d’exemplaires disponibles de chaque livre d’une bibliothèque publique. Supposons que ce jeu de données présente deux champs : isbn, qui représente le numéro ISBN du livre, et number_of_copies, qui suit le nombre d’exemplaires actuellement disponibles dans la bibliothèque. Cela n’aurait pas de sens d’ajouter un enregistrement pour chaque nouvelle valeur du champ number_of_copies, il est en effet préférable de définir la nouvelle valeur number_of_copies sur l’enregistrement correspondant au numéro isbn du livre.

unique ID option in the field dropdown

Afin de configurer un système de ce type avec la plateforme OpenDataSoft, les champs qui seront utilisés en tant que clés uniques doivent être identifiés. Dans notre exemple, la clé unique serait le numéro ISBN, car le reste des données est lié à chaque livre et chaque livre est identifié par son numéro ISBN. L’identification peut être réalisée dans la vue de traitement, depuis le menu qui s’affiche en cliquant sur le bouton en forme d’engrenage. Il est possible de définir plusieurs champs en tant que clés uniques. Ensuite, après avoir enregistré les modifications et publié le jeu de données, si un nouvel enregistrement dont la valeur de clé est égale à celle d’un enregistrement existant est poussé, le nouvel enregistrement écrase l’ancien. C’est-à-dire si votre jeu de données utilise la valeur isbn en tant que clé unique et s’il contient deux de ces enregistrements dans le cas de notre bibliothèque.

[
    {
        "isbn": "978-0060589462",
        "number_of_copies": 3
    }, {
        "isbn": "978-2862744506",
        "number_of_copies": 5
    }
]

Si quelqu’un emprunte un exemplaire de Traité du zen et de l’entretien des motocyclettes, et si vous poussez l’enregistrement ci-dessous, vous disposez toujours de deux enregistrements, le premier étant mis à jour avec la nouvelle valeur.

{
    "isbn": "978-0060589462",
    "number_of_copies": 2
}
table view with 2 records containing respectively 978-0060589462 and 978-2862744506 as isbn and 2 and 5 as number_of_copies

Supprimer des données

Il existe deux points d’entrée permettant de supprimer les enregistrements poussés. Le premier utilise les valeurs des enregistrements, tandis que le second utilise l’ID des enregistrements.

Utiliser les valeurs des enregistrements

Pour supprimer un enregistrement dont vous connaissez les valeurs des champs, utilisez la méthode POST sur l’enregistrement comme si vous l’ajoutiez pour la première fois, mais remplacez /push/ par /delete/ dans l’URL Push. Si votre chemin d’URL Push est /api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/push/?pushkey=<PUSH_API_KEY>, utilisez alors /api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/delete/?pushkey=<PUSH_API_KEY>. Vous trouverez ci-dessous un exemple rapide illustrant la suppression de l’enregistrement que nous avions précédemment poussé.

curl -XPOST <DOMAIN_URL>/api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/delete/?pushkey=<PUSH_API_KEY> -d'{"message":"Hello World!"}'

Utiliser l’ID de l’enregistrement

Si vous connaissez l’ID de l’enregistrement que vous souhaitez supprimer, effectuez simplement une requête GET sur l’URL obtenue en remplaçant /push/ par /<RECORD_ID>/delete/ dans l’URL Push. Vous trouverez ci-dessous un exemple rapide.

curl -XGET <DOMAIN_URL>/api/push/1.0/<DATASET_ID>/<RESSOURCE_ID>/<RECORD_ID>/delete/?pushkey=<PUSH_API_KEY>

Être notifié en cas d’inactivité

inactivity alerting settings in RT resource view

Si vous vous attendez à ce que des données soient fréquemment poussées sur la plateforme, il peut être utile de recevoir une notification dans le cas où la plateforme n’aurait reçu aucun enregistrement depuis un certain temps. Afin d’obtenir des notifications, vous pouvez activer l’option “Alertes” dans la configuration de la source et définir un délai en minutes. Si aucun enregistrement n’a été reçu pendant une période supérieure au délai défini, vous recevrez un e-mail.

Dépublier et désactiver l’API

"disable push" button in RT resource view

Attention : en cas de dépublication de votre jeu de données, les enregistrements existants ne seront pas conservés pour la prochaine publication du jeu de données. Si vous souhaitez éviter de recevoir de nouvelles données, utilisez plutôt le bouton “Désactiver le Push” dans les paramètres de la ressource. Cela empêchera l’utilisation de l’API Push, mais n’aura aucun effet sur les données existantes. Si des données sont poussées alors que le Push est désactivé sur la ressource, aucune donnée ne sera ajoutée et une erreur sera signalée.

Récupération

recovery option in realtime resource view

En cas de perte de données, par exemple lorsque le jeu de données a été dépublié ou lorsqu’un processeur a été configuré de manière incorrecte, il est possible de récupérer les enregistrements perdus. Pour cela, l’option de récupération doit avoir été activée avant que les enregistrements n’aient été poussés vers la plateforme.

recover data button in realtime resource view

Lorsque la récupération est activée, tous les enregistrements reçus par la suite seront sauvegardés et seront éligibles à la récupération. Pour récupérer les enregistrements éligibles, utilisez le bouton “Récupérer des données” sur la page de configuration de la source.