Tutorial

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

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