Anleitung

Wir verwenden einen kleinen Datensatz von Kalev Leetaru, um die Timeseries Insights API zu veranschaulichen. Das Dataset stammt aus dem GDELT Project, einer globalen Datenbank, in der weltweite Ereignisse und die Medienberichterstattung verfolgt werden. Dieses Dataset enthält Erwähnungen von Entitäten in Nachrichten-URLs im April 2019.

Ziele

  • 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 gemäß Einrichtung für Vollzugriff.

Dataset für die Anleitung

Das Dataset enthält unter anderem Anmerkungen zu Standorten, Organisationen und Personen.

Die Timeseries Insights API akzeptiert Eingaben im JSON-Format. Ein Beispiel für ein Ereignis in diesem Dataset ist

{
  "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 Ereigniszeitstempel haben. Es wird empfohlen, dass jedes Ereignis auch einen Long-Wert groupId hat, um zugehörige Ereignisse zu markieren. Ereigniseigenschaften sind als dimensions enthalten. Jede davon hat einen name und einen der folgenden Werte: stringVal, boolVal, longVal oder doubleVal.

{"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 unter Erste Schritte 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",
      ...
    }
  ]
}

In den Ergebnissen werden die Datasets angezeigt, die derzeit dem Projekt untergeordnet sind. Das Feld state gibt an, ob das Dataset verwendet werden kann. Wenn ein Dataset gerade erstellt wurde, hat es den Status LOADING, bis die Indexierung abgeschlossen ist. Danach wechselt es in den Status LOADED. Wenn beim Erstellen und Indexieren Fehler auftreten, befindet sich der Datensatz im Status FAILED. Die Ergebnisse enthalten auch die vollständigen Dataset-Informationen 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

Dabei enthält create.json Folgendes:

{
  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 Dataset mit dem Namen dataset_tutorial aus GCS dataSources erstellt, das Ereignisdaten im JSON-Format enthält. Nur die in dataNames aufgeführten Dimensionen werden indexiert und vom System verwendet.

Die Erstellungsanfrage wird als erfolgreich zurückgegeben, wenn sie vom API-Server akzeptiert wird. Der Datensatz hat den Status LOADING, bis die Indexierung abgeschlossen ist. Danach ändert sich der Status zu LOADED. Ab diesem Zeitpunkt können Abfragen und gegebenenfalls Aktualisierungen für den Datensatz ausgeführt werden.

Dataset abfragen

Mit projects.locations.datasets.query werden Anomalieerkennungsabfragen ausgeführt.

gcurl -X POST -d @query.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:query

Dabei enthält query.json Folgendes:

{
  "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 Ereignisdatensätze im Streamingverfahren hinzugefügt.

gcurl -X POST -d @append.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:appendEvents

Dabei enthält append.json Folgendes (bitte ersetzen Sie eventTime durch einen Zeitstempel, der nahe an der aktuellen Zeit liegt):

{
  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 Aktualisierungen werden nahezu in Echtzeit indexiert, sodass Änderungen schnell in den Suchergebnissen berücksichtigt werden können. Alle Ereignisse, die von einer einzelnen projects.locations.datasets.appendEvents-Anfrage gesendet werden, müssen denselben 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 das Dataset akzeptiert keine zusätzlichen Anfragen oder Aktualisierungen. Es kann einige Zeit dauern, bis die Daten vollständig aus dem Dienst entfernt wurden. Danach wird dieses Dataset nicht mehr von „List datasets“ zurückgegeben.

Nächste Schritte

Auf der GDELT-Website finden Sie weitere Beispiele, wenn Sie nach „Timeseries Insights API“ suchen.