Anleitung

Wir verwenden ein kleines Dataset, Kalev Leetaru zur Veranschaulichung der Zeitreihe Insights API Das Dataset wird aus GDELT-Projekt, ein globales Datenbank-Tracking zum Weltgeschehen und in der Medienberichterstattung. Dieses Dataset enthält Entitätserwähnungen in Nachrichten-URLs im April 2019.

Lernziele

  • Informationen zum Datenformat für die Timeseries Insights API.
  • 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 Einrichtung für vollständigen Zugriff.

Dataset für Tutorials

Das Dataset enthält Annotationen zu Entitäten von Standorten, Organisationen, Personen, unter anderem.

Die Timeseries Insights API akzeptiert Eingaben im JSON-Format. Eine Stichprobe Ereignis für dieses Dataset

{
  "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. Bevorzugt Jedes Ereignis hat außerdem einen langfristigen groupId, um zugehörige Ereignisse zu markieren. Ereignis Attribute sind als dimensions enthalten, die jeweils ein name und eines der folgenden Werte haben: stringVal, boolVal, longVal oder doubleVal.

{"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 ist eine Umgebungsvariable, die beide in Erste Schritte.

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 zeigen die Datasets, die sich derzeit im Projekt befinden. Das Feld state gibt an, ob das Dataset einsatzbereit ist. Wenn ein Dataset nur erstellt wurde, befindet er sich im Status LOADING, bis die Indexierung abgeschlossen ist, und geht dann über in den Status LOADED geändert. Falls bei der Erstellung und Indexierung Fehler auftreten, im Status FAILED. Die Ergebnisse enthalten auch die vollständigen Dataset-Informationen aus der ursprünglichen Anfrage zur Erstellung.

Dataset erstellen

projects.locations.datasets.create dem Projekt ein neues Dataset hinzugefügt wird.

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"}
  ]
}

Diese Anfrage erstellt ein Dataset mit dem Namen dataset_tutorial aus GCS. dataSources, die Ereignisdaten im JSON-Format enthalten. Nur Dimensionen aufgeführt in dataNames werden vom System indexiert und verwendet.

Die Erstellungsanfrage wird als erfolgreich zurückgegeben, wenn sie vom API-Server akzeptiert wird. Die befindet sich das Dataset bis zum Abschluss der Indexierung im Status LOADING, dann wird zu LOADED. Danach kann das Dataset Abfragen annehmen und gegebenenfalls aktualisiert.

Dataset abfragen

projects.locations.datasets.query führt Anomalieerkennungsabfragen durch.

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

projects.locations.datasets.appendEvents fügt Ereignisdatensätze im Streaming-Modus hinzu.

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

wobei append.json enthält (ersetze eventTime durch einen Zeitstempel, der ungefähr dem aktuellen Zeitpunkt 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 Sie schnell auf Änderungen reagieren können. Abfrageergebnisse. Alle Ereignisse, die von einem einzelnen projects.locations.datasets.appendEvents Anfrage muss 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 Updates erhalten. Es kann einige Zeit dauern, bis die Daten vollständig entfernt sind aus dem Dienst, woraufhin dieses Dataset beim Auflisten von Datasets nicht mehr zurückgegeben wird.

Nächste Schritte

Weitere Beispiele finden Sie unter GDELT-Website durch die Suche nach „Timeseries“. Insights API“ hinzu.