チュートリアル

Kalev Leetaru が提供している小さなデータセットを使用して、Timeseries Insightss API について説明します。このデータセットは、世界的なイベントとメディア報道をトラッキングするグローバルデータベースである GDELT Project に由来しています。このデータセットには、2019 年 4 月のニュース URL におけるエンティティへの言及が含まれています。

目標

Timeseries Insights API のデータ形式について学習します。
データセットを作成、クエリ、更新、削除する方法について説明します。

準備

Cloud プロジェクトを設定し、フルアクセスのセットアップに従って Timeseries Insights API を有効にします。

チュートリアルデータセット

データセットには、場所、組織、人などのエンティティアノテーションが含まれています。

Timeseries Insights API は JSON 形式の入力を取得します。このデータセットのサンプルイベントは次のとおりです。

{
  "groupId":"-6180929807044612746",
  "dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],
  "eventTime":"2019-04-05T08:00:00+00:00"
}

各イベントには、イベントのタイムスタンプの eventTime フィールドが必要です。関連するイベントをマークするために、各イベントには長い値の groupId も設定することをおすすめします。イベントのプロパティは dimensions として含まれ、それぞれに name と stringVal、boolVal、longVal、doubleVal のいずれか 1 つが含まれます。

{"groupId":"-6180929807044612746","dimensions":[{"name":"EntityORGANIZATION","stringVal":"Medina Gazette"}],"eventTime":"2019-04-05T08:00:00+00:00"}

データセットのリスト表示

projects.locations.datasets.list は、${PROJECT_ID} の下にあるすべてのデータセットを表示します。gcurl はエイリアスで、PROJECT_ID は環境変数です。両方とも利用の開始で設定されます。

gcurl https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets

結果は次のような JSON 文字列です。

{
  "datasets": [
    {
      "name": "example",
      "state": "LOADED",
      ...
    },
    {
      "name": "dataset_tutorial",
      "state": "LOADING",
      ...
    }
  ]
}

結果には、現在プロジェクトにあるデータセットが表示されます。state フィールドは、データセットが使用できる状態かどうかを示します。データセットが作成されると、インデックス作成が完了するまで LOADING 状態になり、LOADED 状態に移行します。作成とインデックス登録でエラーが発生した場合、状態は FAILED になります。結果には、元の作成リクエストからの完全なデータセット情報も含まれます。

データセットを作成する

projects.locations.datasets.create は、新しいデータセットをプロジェクトに追加します。

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

create.json の内容は次のとおりです。

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

このリクエストにより、GCS の dataSources から dataset_tutorial という名前のデータセットが作成されます。これには、JSON 形式のイベントデータが含まれます。dataNames に一覧表示されているディメンションのみがインデックスに登録され、システムによって使用されます。

API サーバーが受け入れた場合、作成リクエストは成功を返します。データセットは、インデックス登録が完了するまで LOADING 状態になり、状態は LOADED になります。その後、データセットはクエリと更新（ある場合）を受け入れられるようになります。

クエリデータセット

projects.locations.datasets.query は、異常検出クエリを実行します。

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

query.json の内容は次のとおりです。

{
  "detectionTime": "2019-04-15T00:00:00Z",
  "numReturnedSlices": 5,
  "slicingParams": {
    "dimensionNames": ["EntityLOCATION"]
  },
  "timeseriesParams": {
    "forecastHistory": "1209600s",
    "granularity": "86400s"
  },
  "forecastParams": {
    "noiseThreshold": 100.0
  },
}

クエリ結果は次のようになります。

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

ストリーミング更新

projects.locations.datasets.appendEvents は、ストリーミング方式でイベントレコードを追加します。

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

ここで、append.json には以下が含まれます（eventTime を現在の時刻に近いタイムスタンプに置き換えてください）。

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

ストリーミングされた更新はほぼリアルタイムでインデックス登録されるため、クエリ結果で変更にすばやく対応できます。1 つの projects.locations.datasets.appendEvents リクエストによって送信されるすべてのイベントには、同じ groupdId が必要です。

データセットの削除

projects.locations.datasets.delete は、データセットに削除のマークを付けます。

gcurl -X DELETE https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial

リクエストはすぐに返され、データセットは追加のクエリや更新を受け入れません。データがサービスから完全に削除されるまでにしばらく時間がかかる場合があります。その後、List データセットはこのデータセットを返しません。

次のステップ

Timeseries Insights API のコンセプト
REST API の詳細

他の例については、GDELT のウェブサイトで「Timeseries Insights API」について検索してください。