我们使用 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”找到其他一些示例。