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 de Le projet GDELT, un outil mondial de suivi des bases de données les événements mondiaux et la couverture médiatique. Cet ensemble de données contient des mentions d'entités dans URL Google Actualités en avril 2019.
Objectifs
- Découvrez le format de données pour 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 Configurer l'accès complet
Ensemble de données du tutoriel
L'ensemble de données comprend des annotations d'entités indiquant des lieux, des organisations, des personnes, entre autres.
L'API Timeseries Insights accepte des entrées au format JSON. Exemple É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
pour l'horodatage de l'événement. Il est préférable que chaque événement dispose également d'une valeur groupId
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'un des éléments suivants : 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.
PROJECT_ID
est une variable d'environnement, toutes deux configurées dans
Premiers pas.
gcurl https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets
Le résultat est une chaîne JSON semblable à
{
"datasets": [
{
"name": "example",
"state": "LOADED",
...
},
{
"name": "dataset_tutorial",
"state": "LOADING",
...
}
]
}
Les résultats montrent les ensembles de données actuellement inclus dans le projet. Le champ state
indique si l'ensemble de données est prêt à être utilisé. Lorsqu’un jeu de
données est juste
est à l'état LOADING
jusqu'à la fin de l'indexation, puis passe à l'état suivant :
à 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 sur l'ensemble de données 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 contiennent des données d'événement au format JSON. Seules les dimensions listées
dans dataNames
sont indexés et utilisés par le système.
La requête de création renvoie un résultat positif si elle est acceptée par le serveur d'API. Le jeu de données est à l'état LOADING
jusqu'à ce que l'indexation soit terminée, puis son état devient LOADED
. Le jeu de données peut 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 ressemble à ceci:
{
"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 sous forme de 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 par flux sont indexées en temps quasi réel afin que les modifications puissent s'adapter rapidement
les résultats de la requête. Tous les événements envoyés par un même
projects.locations.datasets.appendEvents
doit avoir le même groupdId
.
Supprimer un ensemble de données
projects.locations.datasets.delete marque l'ensemble de données à supprimer.
gcurl -X DELETE https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial
La requête est renvoyée immédiatement, et l'ensemble de données n'accepte pas 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. Une fois cette opération effectuée, la liste des ensembles de données ne renverra plus cet ensemble de données.
Étape suivante
Vous trouverez d'autres exemples sur site Web GDELT en recherchant "Timeseries" API Insights".