Diese Seite wurde von der Cloud Translation API übersetzt.

Anleitung

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. 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 die Anleitung

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

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 das Dataset 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. 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 um dem Projekt ein neues Dataset hinzuzufügen.

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 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

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

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

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

Konzepte der Timeseries Insights API
Weitere Informationen zur REST API

Weitere Beispiele finden Sie auf der GDELT-Website. Suchen Sie dort nach „Timeseries Insights API“.