Nous utilisons un petit ensemble de données fourni par Kalev Leetaru pour illustrer l'API Timeseries Insights. L'ensemble de données est issu du projet GDELT, une base de données mondiale qui suit les événements mondiaux et la couverture médiatique. Cet ensemble de données contient des mentions d'entités dans les URL d'actualités en avril 2019.
Objectifs
- Découvrez le format de données de l'API Timeseries Insights.
- Découvrez comment créer, interroger, mettre à jour et supprimer des ensembles de données.
Avant de commencer
Configurez un projet Cloud et activez l'API Timeseries Insights en suivant la configuration de l'accès complet.
Ensemble de données du tutoriel
L'ensemble de données comprend des annotations d'entités de lieux, d'organisations, de personnes, etc.
L'API Timeseries Insights accepte des entrées au format JSON. Voici un exemple d'événement pour cet ensemble de données :
{
"groupId":"-6180929807044612746",
"dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],
"eventTime":"2019-04-05T08:00:00+00:00"
}
Chaque événement doit comporter un champ eventTime correspondant à l'horodatage de l'événement. Il est préférable que chaque événement dispose également d'un groupId de valeur longue pour marquer les événements associés. Les propriétés d'événement sont incluses en tant que dimensions, chacune ayant un name et l'une des stringVal, boolVal, longVal ou doubleVal.
{"groupId":"-6180929807044612746","dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],"eventTime":"2019-04-05T08:00:00+00:00"}
Répertorier des ensembles de données
projects.locations.datasets.list affiche tous les ensembles de données sous ${PROJECT_ID}. gcurl est un alias et PROJECT_ID est une variable d'environnement, tous deux configurés dans la section Premiers pas.
gcurl https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets
Le résultat est une chaîne JSON telle que
{
"datasets": [
{
"name": "example",
"state": "LOADED",
...
},
{
"name": "dataset_tutorial",
"state": "LOADING",
...
}
]
}
Les résultats montrent les ensembles de données actuellement sous le projet. Le champ state indique si l'ensemble de données est prêt à être utilisé. Lorsqu'un ensemble de données vient d'être créé, il possède l'état LOADING jusqu'à la fin de l'indexation, puis passe à l'état LOADED. Si des erreurs se produisent lors de la création et de l'indexation, l'état est FAILED. Les résultats incluent également les informations complètes de l'ensemble de données issues de la requête de création d'origine.
Créer un ensemble de données
projects.locations.datasets.create ajoute un nouvel ensemble de données au projet.
gcurl -X POST -d @create.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets
où create.json contient:
{
name: "dataset_tutorial",
dataNames: [
"EntityCONSUMER_GOOD",
"EntityEVENT",
"EntityLOCATION",
"EntityORGANIZATION",
"EntityOTHER",
"EntityPERSON",
"EntityUNKNOWN",
"EntityWORK_OF_ART",
],
dataSources: [
{uri: "gs://data.gdeltproject.org/blog/2021-timeseries-insights-api/datasets/webnlp-201904.json"}
]
}
Cette requête crée un ensemble de données nommé dataset_tutorial à partir de GCS dataSources, qui contient des données d'événement au format JSON. Seules les dimensions listées dans dataNames sont indexées et utilisées par le système.
La requête de création renvoie un résultat positif si le serveur d'API l'accepte. L'ensemble de données restera à l'état LOADING jusqu'à la fin de l'indexation, puis il passera à l'état LOADED. L'ensemble de données pourra alors commencer à accepter les requêtes et les mises à jour, le cas échéant.
Interroger l'ensemble de données
projects.locations.datasets.query effectue des requêtes de détection d'anomalies.
gcurl -X POST -d @query.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:query
où query.json contient:
{
"detectionTime": "2019-04-15T00:00:00Z",
"numReturnedSlices": 5,
"slicingParams": {
"dimensionNames": ["EntityLOCATION"]
},
"timeseriesParams": {
"forecastHistory": "1209600s",
"granularity": "86400s"
},
"forecastParams": {
"noiseThreshold": 100.0
},
}
Le résultat de la requête se présente comme suit:
{
"name": "projects/timeseries-staging/locations/us-central1/datasets/webnlp-201901-202104-dragosd",
"slices": [
{
"dimensions": [
{
"name": "EntityLOCATION",
"stringVal": "Notre Dame"
}
],
"detectionPointActual": 1514,
"detectionPointForecast": 15.5,
"expectedDeviation": 5.5,
"anomalyScore": 14.203791469194313,
"status": {}
},
{
"dimensions": [
{
"name": "EntityLOCATION",
"stringVal": "Seine"
}
],
"detectionPointActual": 1113,
"detectionPointForecast": 14,
"expectedDeviation": 15,
"anomalyScore": 9.5565217391304351,
"status": {}
},
{
"dimensions": [
{
"name": "EntityLOCATION",
"stringVal": "Ile de la Cite"
}
],
"detectionPointActual": 852,
"detectionPointForecast": 0,
"expectedDeviation": 1,
"anomalyScore": 8.435643564356436,
"status": {}
},
{
"dimensions": [
{
"name": "EntityLOCATION",
"stringVal": "Paris"
}
],
"detectionPointActual": 1461,
"detectionPointForecast": 857,
"expectedDeviation": 441,
"anomalyScore": 1.1164510166358594,
"status": {}
},
{
"dimensions": [
{
"name": "EntityLOCATION",
"stringVal": "France"
}
],
"detectionPointActual": 1098,
"detectionPointForecast": 950.5,
"expectedDeviation": 476.5,
"anomalyScore": 0.25585429314830876,
"status": {}
}
]
}
Mise à jour en streaming
projects.locations.datasets.appendEvents ajoute des enregistrements d'événements par flux.
gcurl -X POST -d @append.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:appendEvents
où append.json contient (veuillez remplacer eventTime par un code temporel proche de l'heure actuelle):
{
events: [
{
"groupId":"1324354349507023708",
"dimensions":[{"name":"EntityPERSON","stringVal":"Jason Marsalis"}],
"eventTime":"2022-02-16T15:45:00+00:00"
},{
"groupId":"1324354349507023708",
"dimensions":[{"name":"EntityORGANIZATION","stringVal":"WAFA"}],
"eventTime":"2022-02-16T04:00:00+00:00"
}
]
}
Les mises à jour en flux continu sont indexées quasiment en temps réel afin que les modifications puissent réagir rapidement dans les résultats de requête. Tous les événements envoyés par une seule requête projects.locations.datasets.appendEvents doivent avoir le même groupdId.
Supprimer un ensemble de données
projects.locations.datasets.delete marque l'ensemble de données pour suppression.
gcurl -X DELETE https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial
La requête s'affiche immédiatement, et l'ensemble de données n'accepte plus de requêtes ni de mises à jour supplémentaires. Il peut s'écouler un certain temps avant que les données ne soient complètement supprimées du service. Passé ce délai, la liste des ensembles de données ne renverra plus cet ensemble de données.
Étapes suivantes
Vous trouverez d'autres exemples sur le site Web de GDELT en recherchant "API Timeseries Insights".