我們使用 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」來查看其他範例。