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 :

  • La planification, qui consiste à republier automatiquement un jeu de données à intervalles fixes. 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.

  • La transmission des données en temps réel 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

Remarque

La disponibilité de cette fonctionnalité dépend de la licence du domaine Opendatasoft.

Les jeux de données peuvent être republiés automatiquement à intervalles fixes.

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.

Ajouter une source distante

Pour planifier un jeu de données, vous devez ajouter une source distante, spécifiée sous la forme d'une URL (HTTP ou FTP) vers un fichier, ou configurer un service distant. Pour plus d'informations, consultez Récupérer un fichier et Configurer un service distant.

Spécifier un intervalle de planification

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

../../_images/scheduling_tab.png

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 domaine.

Important

Les planifications sont définies pour s'exécuter sur le fuseau horaire de Paris, France :

  • En heure normale, les planifications sont exécutées sur le fuseau horaire GMT+1 (heure normale d'Europe centrale).

  • En été, les planifications sont exécutées sur le fuseau horaire GMT+2 (heure d'été d'Europe centrale).

Transmettre des données en temps réel

Remarque

La disponibilité de cette fonctionnalité dépend de la licence du domaine 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.

Configurer le schéma du jeu de données

  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.

Remarque

Les données d'amorçage ne sont pas utilisées dans le jeu de données : leur seul objectif est d'autoriser la configuration du jeu de données.

  1. Configurez les options Information et Gestion des alertes.

  2. Récupérez l'URL Push.

Utiliser 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 domaine, 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 :

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

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é correctement reçus, le serveur envoie la réponse suivante.

{
    "status": "OK"
}

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

Remarque

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.

Pousser un champ de type de fichier

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"
    }
}

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

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 en tant que clés uniques, procédez comme suit :

  1. Dans la zone d'aperçu de l'onglet Traitement, cliquez sur le bouton configuration icon 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 :

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

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

  • isbn, qui représente 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 :

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

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>

Être notifié en cas d'inactivité

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. Sélectionnez action menu icon > Afficher source sur la source désirée.

  3. Cliquez sur Gestion des alertes.

  4. Dans la boîte de dialogue qui s'affiche, configurez les paramètres relatifs aux alertes :

    • Cochez la case Alertes.

    • Spécifiez 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.

Dépublier et désactiver l'API

Lorsque vous dépubliez votre jeu de données, les enregistrements existants ne sont pas conservés pour la prochaine publication du jeu de données.

Procédez comme suit pour éviter d'obtenir de nouvelles données :

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

  2. Sélectionnez action menu icon > Désactiver le Push sur la source désirée.

Cela empêchera l'utilisation de l'API Push, mais n'aura aucun effet sur les données existantes. Si des données sont transmises alors que cette option est désactivée, aucune donnée ne sera ajoutée et une erreur sera envoyée.

Récupérer des données

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. Sélectionnez action menu icon > Récupérer des données sur la source désirée.