Wir verwenden einen kleinen Datensatz von Kalev Leetaru, um die Timeseries Insights API zu veranschaulichen. Der Datensatz stammt aus dem GDELT Project, einer globalen Datenbank, in der weltweite Ereignisse und die Berichterstattung in den Medien erfasst werden. Dieser Datensatz enthält Erwähnungen von Entitäten 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. Folgen Sie dazu der Anleitung unter Für vollständigen Zugriff einrichten.
Dataset für die Anleitung
Der Datensatz enthält unter anderem Entitätsannotierungen für Orte, Organisationen und Personen.
Die Timeseries Insights API akzeptiert Eingaben im JSON-Format. Ein Beispiel für ein Ereignis in diesem Datensatz:
{
"groupId":"-6180929807044612746",
"dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],
"eventTime":"2019-04-05T08:00:00+00:00"
}
Jedes Ereignis muss ein Feld eventTime für den Zeitstempel des Ereignisses haben. Es wird empfohlen, jedem Ereignis auch einen groupId mit einem langen Wert zuzuweisen, um zugehörige Ereignisse zu markieren. Ereigniseigenschaften werden als dimensions eingefügt, die jeweils einen name und einen Wert aus stringVal, boolVal, longVal oder doubleVal haben.
{"groupId":"-6180929807044612746","dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],"eventTime":"2019-04-05T08:00:00+00:00"}
Datasets auflisten
Mit projects.locations.datasets.list werden alle Datasets unter ${PROJECT_ID} angezeigt. gcurl ist ein Alias und PROJECT_ID eine Umgebungsvariable, die beide im Abschnitt Einstieg eingerichtet wurden.
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",
...
}
]
}
Die Ergebnisse enthalten die Datasets, die sich derzeit im Projekt befinden. Das Feld state gibt an, ob der Datensatz einsatzbereit ist. Wenn ein Datensatz gerade erstellt wurde, hat er den Status LOADING, bis die Indexierung abgeschlossen ist. Dann wechselt er in den Status LOADED. Wenn beim Erstellen und Indexieren Fehler auftreten, hat das Asset den Status FAILED. Die Ergebnisse enthalten auch die vollständigen Datensatzinformationen aus der ursprünglichen Erstellungsanfrage.
Dataset erstellen
Mit projects.locations.datasets.create wird dem Projekt ein neues Dataset hinzugefügt.
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"}
]
}
Mit dieser Anfrage wird ein Datensatz mit dem Namen dataset_tutorial aus GCSdataSources erstellt, der Ereignisdaten im JSON-Format enthält. Nur in dataNames aufgeführte Dimensionen werden indexiert und vom System verwendet.
Die Anfrage zum Erstellen gibt „success“ zurück, wenn sie vom API-Server akzeptiert wird. Der Datensatz hat den Status LOADING, bis die Indexierung abgeschlossen ist. Danach ändert er sich in LOADED. Ab diesem Zeitpunkt können Abfragen und Aktualisierungen für den Datensatz angenommen werden.
Dataset abfragen
Mit projects.locations.datasets.query werden Abfragen zur Anomalieerkennung ausgeführt.
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 per Streaming hinzugefügt.
gcurl -X POST -d @append.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:appendEvents
wobei append.json Folgendes enthält (ersetzen Sie eventTime durch einen Zeitstempel, der der aktuellen Uhrzeit nahekommt):
{
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, damit Änderungen schnell in den Abfrageergebnissen berücksichtigt werden können. Alle Ereignisse, die mit einer einzelnen projects.locations.datasets.appendEvents-Anfrage gesendet werden, müssen dieselbe groupdId haben.
Dataset löschen
Mit projects.locations.datasets.delete wird das Dataset zum Löschen markiert.
gcurl -X DELETE https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial
Die Anfrage wird sofort zurückgegeben und der Datensatz akzeptiert keine weiteren Abfragen oder Aktualisierungen. Es kann einige Zeit dauern, bis die Daten vollständig aus dem Dienst entfernt wurden. Danach wird der Datensatz nicht mehr in Listen zurückgegeben.
Nächste Schritte
Weitere Beispiele finden Sie auf der GDELT-Website. Suchen Sie dort nach „Timeseries Insights API“.