教學課程

我們使用 Kalev Leetaru 提供的小型資料集，說明 Timeseries Insights API。資料集源自 GDELT 專案，這是追蹤全球事件和媒體報導的全球資料庫。這個資料集包含 2019 年 4 月新聞網址中提及實體的內容。

目標

  • 瞭解 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 其中一個。

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

串流更新會近乎即時索引，因此變更可快速回應查詢結果。單一 projects.locations.datasets.appendEvents 要求傳送的所有事件都必須具有相同的 groupdId。

刪除資料集

projects.locations.datasets.delete 會將資料集標示為刪除。

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

要求會立即傳回，資料集也不會接受其他查詢或更新。資料可能需要一段時間才能從服務中完全移除，之後「List」資料集就不會傳回這個資料集。

後續步驟

您也可以在 GDELT 網站上搜尋「Timeseries Insights API」來查看其他範例。