本頁面由 Cloud Translation API 翻譯而成。

教學課程

我們使用 Kalev Leetaru 提供的小型資料集，說明 Timeseries Insights API。這項資料集衍生自全球事件資料庫 (GDELT) 專案，這個全球資料庫會追蹤世界各地發生的事件和媒體報導。這個資料集包含 2019 年 4 月新聞網址中提及的實體。

教學課程資料集

資料集包含地點、機構、人物等實體的註解。

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

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