Maintenir les données à jour

La plateforme Opendatasoft permet de gérer des jeux de données statiques (qui doivent être publiés une seule fois) et des jeux de données en direct (qui doivent être régulièrement mis à jour).

Deux mécanismes différents sont disponibles :

• La planification consiste à faire republier automatiquement un jeu de données à intervalles fixes. Ce mode est particulièrement utile pour un jeu de données avec une source régulièrement mise à jour.

• La transmission des données en temps réel sur la plateforme Opendatasoft peut être 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.

La disponibilité de cette fonctionnalité dépend de votre plan Opendatasoft.

Les jeux de données peuvent être automatiquement republiés à intervalles fixes. C’est la solution la plus simple à mettre en œuvre. Il ne nécessite aucun codage, seulement une source adaptée et quelques réglages dans la configuration du jeu de données.

Pour planifier un jeu de données, vous devez ajouter une source adaptée : un fichier via une adresse FTP ou HTTP, ou bien un service distant. Pour plus d'informations, consultez Récupérer un fichier et Configurer un service distant.

Une fois que vous avez enregistré un jeu de données avec une source distante, l'onglet Planification est activé :

Depuis cet onglet, vous pouvez ajouter autant de planifications que vous voulez. Par exemple, en adéquation avec vos besoins, vous pouvez choisir de planifier le retraitement d'un jeu de données tous les lundis matin et tous les mercredis après-midi.

Par défaut, l'intervalle de planification minimale est exprimé en journées. Veuillez contacter le support d'Opendatasoft si vous avez besoin d'une planification exprimée en minutes sur votre espace de travail.

Les planifications sont définies pour s'exécuter sur le fuseau horaire de Paris, France. Ce fuseau est fixe et indépendant du fuseau horaire de votre espace de travail.En heure normale, cela signifie que les horaires fonctionnent à l'heure d'Europe centrale (CET), ou en d'autres termes à GMT+1. En été, les horaires fonctionnent à l'heure d'été de l'Europe centrale (CEST), c'est-à-dire à GMT+2. Notez que dans les pays qui utilisent l'heure d'été, les pays peuvent passer à des dates différentes.

La disponibilité de cette fonctionnalité dépend de la licence de votre espace de travail Opendatasoft.

Pour certains types de données, il peut être utile de transmettre les données plutôt que de suivre le modèle classique d'extraction des données par la plateforme à partir d'une ressource. Pour répondre à ce besoin, la plateforme Opendatasoft propose une API Push en temps réel.

Cela ne doit pas être confondu avec la possibilité de planifier le traitement des jeux de données. Lors de la planification, le jeu de données extraira la ressource et traitera les données qu'elle contient de façon périodique. À l'inverse, avec l'API Push, le jeu de données est alimenté par une application via une API Push, et les enregistrements sont traités les uns après les autres dès leur réception.

1. Dans Catalogue > Jeux de données, cliquez sur le bouton Nouveau jeu de données

2. Sélectionnez Realtime dans l'assistant qui s'ouvre, sous la section Configurer un service distant

3. Dans le champ Schéma de données en temps réel, indiquez des données d'amorçage. Les données doivent inclure tous les champs qui seront envoyés via l'API.

Les données bootstrap ne sont pas utilisées dans le jeu de données : leur seul but est de permettre la configuration du jeu de données.

1. Configurez les options Information et Gestion des alertes

2. Récupérez l'URL Push

Après avoir configuré les paramètres de la source en temps réel, un chemin d'accès d'URL comprenant une clé d'API Push s'affiche. Ce chemin d'accès, ajouté à l'URL de base de votre espace de travail, correspond à l'emplacement où la plateforme recevra les données après la publication.

Les données doivent être envoyées au format JSON : - Sous la forme d'un objet JSON unique pour un seul enregistrement. - Sous la forme d'un tableau d'objets JSON pour transmettre plusieurs enregistrements à la fois.

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>/<RESOURCE_ID>/push/?pushkey=<PUSH_API_KEY> -d'{"message":"Hello World!"}'

Voici le jeu de données résultant :

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>/<RESOURCE_ID>/push/?pushkey=<PUSH_API_KEY> -d'[{"message":"¡Hola Mundo!"},{"message":"Hallo Welt!"}]'

Si les enregistrements ont été reçus correctement, le serveur enverra la réponse suivante.

{
 "status": "OK"
 }

Si une erreur se produisait lors de la tentative de poussée d'un enregistrement, la réponse spécifierait l'erreur.

Les requêtes Push en temps réel sont limitées à une charge utile de 5 Mo. Une erreur est déclenchée si ce seuil est dépassé ; la charge utile doit donc être répartie entre plusieurs requêtes de taille moins importante.

Pour transmettre un champ de type image, un objet JSON contenant les données encodées en base64 et le type MIME du fichier doit être envoyé :

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

Parfois, il est utile de mettre à jour les enregistrements existants plutôt que d'en transmettre de nouveaux. Pour configurer un tel système avec la plateforme Opendatasoft, les champs utilisés en tant que clés uniques doivent être marqués comme tels.

Procédure

Pour marquer des champs comme une clé unique, procédez comme suit :

1. Dans la zone d'aperçu de l'onglet Traitement, cliquez sur la molette du champ de votre choix

2. Sélectionnez ID unique

3. Enregistrez et publiez le jeu de données

Si un nouvel enregistrement avec une valeur de clé égale à un enregistrement existant est transmis, le nouvel enregistrement remplace l'ancien enregistrement.

Exemple

Un jeu de données suit le nombre d'exemplaires disponibles pour chaque livre dans une bibliothèque municipale :

Imaginons que ce jeu de données contient deux champs :

• isbn , représentant le numéro ISBN du livre

• number_of_copies qui suit le nombre actuel d'exemplaires disponibles dans la bibliothèque.

Dans cette situation, ajouter un enregistrement pour chaque nouvelle valeur du champ number_of_copies n'est pas pertinent. Il serait plus judicieux de définir la nouvelle valeur number_of_copies sur l'enregistrement correspondant au champ isbn du livre.

Dans cet exemple, la clé unique serait isbn, car le reste des données est associé à chaque livre, et ces livres sont identifiés par l'ISBN.

Si votre jeu de données a isbn comme clé unique et contient ces deux enregistrements :

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

Si quelqu'un emprunte un exemplaire du Traité du zen et de l'entretien des motocyclettes et que vous transmettez l'enregistrement suivant :

{
 "isbn": "978-0060589462",
 "number_of_copies": 2
 }

Vous avez toujours deux enregistrements, le premier ayant été mis à jour avec la nouvelle valeur :

Deux points d'entrée permettent de supprimer les enregistrements transmis. Le premier utilise les valeurs des enregistrements, tandis que le second utilise l'ID des enregistrements.

Supprimer des données à l'aide des 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'accès 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>.

Voici un exemple simple illustrant la suppression de l'enregistrement que nous avons transmis précédemment :

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

Supprimer des données à l'aide de l'ID des enregistrements

Si vous connaissez l'ID de l'enregistrement que vous souhaitez supprimer, effectuez une requête GET sur l'URL Push en remplaçant /push/par /<RECORD_ID>/delete/ :

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

Supprimer toutes les données d'un dataset

L'API Push ne permet pas de vider un jeu de données, et ce n'est pas une méthode que nous recommandons (à la place, par exemple, un serveur FTP pourrait être plus approprié).

Néanmoins, il existe toutefois une solution au travers l'API Automation permettant de le faire par plusieurs appels à l'API.

Pour cela, il est nécessaire de dépublier et de republier le jeu de données, l'ensemble des données contenues dans le dataset sera alors supprimé. Voici les liens vers la documentation de l'API Automation, pour dépublier et publier un jeu de données et les URLs à appeler pour ces opérations:

• Dépublication d'un jeu de données :

curl -X POST <DOMAIN_URL>/api/automation/1.0/datasets/<DATASET_UID>/unpublish?pushkey=<PUSH_API_KEY>

• Publication d'un jeu de données :

curl -X POST <DOMAIN_URL>/api/automation/1.0/datasets/<DATASET_UID>/publish?pushkey=<PUSH_API_KEY>

Il est important de noter que l'identifiant est bien le Dataset UID et non Dataset ID lors de l'appel à l'API Automation.Pour obtenir l'UID à partir de l'identifiant, il est nécessaire de faire un appel au préalable à l'API Automation:<DOMAIN_URL>/api/automation/1.0/datasets/?dataset_id=<DATASET_ID>

Si vous vous attendez à ce que des données soient fréquemment transmises à 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.

Procédez comme suit pour recevoir des notifications :

1. Dans Catalogue > Jeux de données, cliquez sur le jeu de données souhaité

2. Afficher la source désirée

3. Cliquez sur Gestion des alertes

4. Dans la boîte de dialogue qui s'ouvre, configurez les paramètres d'alerte :

   • Cochez la case Alerte

   • Entrez un seuil en minutes dans la case Alerte d'inactivité

Si aucun enregistrement n'a été reçu pendant une période supérieure au délai défini, vous recevrez un e-mail.

Lorsque vous annulez la publication de votre ensemble de données, les enregistrements existants ne sont pas conservés pour la prochaine publication de l'ensemble de données.

Pour éviter d'obtenir de nouvelles données, procédez comme suit :

1. Dans Catalogue > Jeux de données, cliquez sur le jeu de données souhaité

2. Puis Afficher la source désirée et Désactiver le Push

Cela empêchera l'utilisation de l'API push mais n'affectera pas les données existantes. Si les données sont poussées alors que la poussée est désactivée, aucune donnée ne sera ajoutée et une erreur sera envoyée.

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.

Tous les enregistrements reçus sont sauvegardés et peuvent être récupérés.

Procédez comme suit pour récupérer les enregistrements éligibles :

1. Dans Catalogue > Jeux de données, cliquez sur le jeu de données souhaité

2. Puis sur la source souhaitée, Récupérer des données