Wir verwenden ein kleines Dataset, das von Kalev Leetaru bereitgestellt wird, um die Timeseries Insights API zu veranschaulichen. Das Dataset stammt aus The GDELT Project, einer globalen Datenbank, in der weltweite Ereignisse und Medienberichte erfasst werden. Dieses Dataset enthält Entitätserwähnungen in Nachrichten-URLs im April 2019.
Lernziele
- Informationen zum Datenformat für die Timeseries Insights API.
- Hier erfahren Sie, wie Sie Datasets erstellen, abfragen, aktualisieren und löschen.
Hinweise
Richten Sie ein Cloud-Projekt ein und aktivieren Sie die Timeseries Insights API nach der Einrichtung für den vollen Zugriff.
Anleitungs-Dataset
Das Dataset enthält Entitätsanmerkungen von Orten, Organisationen, Personen usw.
Die Timeseries Insights API verwendet Eingaben im JSON-Format. Ein Beispiel-Ereignis für dieses Dataset ist
{
"groupId":"-6180929807044612746",
"dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],
"eventTime":"2019-04-05T08:00:00+00:00"
}
Jedes Ereignis muss ein eventTime
-Feld für den Ereigniszeitstempel haben. Idealerweise hat jedes Ereignis auch einen langwertigen groupId
, um verwandte Ereignisse zu markieren. Ereignisattribute werden als dimensions
eingeschlossen, von denen jedes eine name
und entweder stringVal
, boolVal
, longVal
oder doubleVal
hat.
{"groupId":"-6180929807044612746","dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],"eventTime":"2019-04-05T08:00:00+00:00"}
Datasets auflisten
projects.locations.datasets.list zeigt alle Datasets unter ${PROJECT_ID}
an. gcurl
ist ein Alias und PROJECT_ID
eine Umgebungsvariable. Beide werden unter Erste Schritte eingerichtet.
gcurl https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets
Das Ergebnis ist ein JSON-String wie
{
"datasets": [
{
"name": "example",
"state": "LOADED",
...
},
{
"name": "dataset_tutorial",
"state": "LOADING",
...
}
]
}
In den Ergebnissen werden die Datasets angezeigt, die sich derzeit im Projekt befinden. Das Feld state
gibt an, ob das Dataset verwendet werden kann. Ein gerade erstelltes Dataset befindet sich bis zum Abschluss der Indexierung im Status LOADING
und wechselt dann in den Status LOADED
. Wenn beim Erstellen und Indexieren Fehler auftreten, ist der Status FAILED
. Die Ergebnisse enthalten auch die vollständigen Dataset-Informationen aus der ursprünglichen Erstellungsanfrage.
Dataset erstellen
projects.locations.datasets.create fügt dem Projekt ein neues Dataset hinzu.
gcurl -X POST -d @create.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets
wobei create.json
Folgendes enthält:
{
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"}
]
}
Durch diese Anfrage wird aus GCS dataSources
ein Dataset mit dem Namen dataset_tutorial
erstellt, das Ereignisdaten im JSON-Format enthält. Nur in dataNames
aufgeführte Dimensionen werden vom System indexiert und verwendet.
Die Erstellungsanfrage gibt erfolgreich zurück, wenn sie vom API-Server akzeptiert wird. Das Dataset hat bis zum Abschluss der Indexierung den Status LOADING
. Anschließend wechselt er zu LOADED
. Danach kann das Dataset Abfragen annehmen und ggf. Aktualisierungen vornehmen.
Dataset abfragen
projects.locations.datasets.query führt Abfragen zur Anomalieerkennung durch.
gcurl -X POST -d @query.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:query
wobei query.json
Folgendes enthält:
{
"detectionTime": "2019-04-15T00:00:00Z",
"numReturnedSlices": 5,
"slicingParams": {
"dimensionNames": ["EntityLOCATION"]
},
"timeseriesParams": {
"forecastHistory": "1209600s",
"granularity": "86400s"
},
"forecastParams": {
"noiseThreshold": 100.0
},
}
Das Abfrageergebnis sieht so aus:
{
"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": {}
}
]
}
Streaming-Update
Mit projects.locations.datasets.appendEvents werden Ereigniseinträge gestreamt.
gcurl -X POST -d @append.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:appendEvents
wobei append.json
enthält (bitte ersetzen Sie eventTime
durch einen Zeitstempel, der der aktuellen Uhrzeit entspricht):
{
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"
}
]
}
Gestreamte Updates werden nahezu in Echtzeit indexiert, sodass Änderungen schnell in den Abfrageergebnissen reagieren können. Alle Ereignisse, die von einer einzelnen projects.locations.datasets.appendEvents-Anfrage gesendet werden, müssen dieselbe groupdId
haben.
Dataset löschen
projects.locations.datasets.delete markiert das Dataset zum Löschen.
gcurl -X DELETE https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial
Die Anfrage wird sofort zurückgegeben und das Dataset akzeptiert keine weiteren Abfragen oder Aktualisierungen. Es kann einige Zeit dauern, bis die Daten vollständig aus dem Dienst entfernt wurden. Danach wird dieses Dataset nicht mehr zurückgegeben.
Nächste Schritte
- Timeseries Insights API-Konzepte
- Weitere Informationen zur REST API
Weitere Beispiele finden Sie auf der GDELT-Website, wenn Sie nach „Timeseries Insights API“ suchen.