教程

---

我们使用由 Google 提供的 Kalev Leetaru 来说明时间序列 Insights API。数据集来源于 GDELT 项目：全球数据库跟踪 全球事件和媒体报道。此数据集包含提及的实体 。

目标

• 了解 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。

注意 ：Google Cloud API 接受驼峰式大小写（如 camelCase）和蛇形 大小写形式（例如 snake_case）。文档大多采用驼峰式命名法。

注意：由于 JSON 长值（数字）实际上是仅具有整数精度的浮点值，因此如果 JSON 使用数字，groupId 和 longVal 实际上都限制为 53 个二进制数字。要提供 int64 数据，JSON 值应 以字符串形式括起来。groupId 通常是数字 ID，或使用确定性哈希函数生成，符合上述限制。

注意：name 字段应为字母数字值，包括 '_'。不支持特殊字符（包括空格）。stringVal 字段支持有效的 Unicode 字符。

注意 ：从静态 Google Cloud Storage 数据源读取数据时，每个 JSON 文件 事件应为一行（也称为 JSON 行格式），如下所示：

{"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 中创建一个名为 dataset_tutorial 的数据集 dataSources，其中包含 JSON 格式的事件数据。只有 dataNames 中列出的维度才会被编入索引并由系统使用。

如果 API 服务器接受了创建请求，则返回成功。数据集将处于 LOADING 状态，直到编制索引完成，然后状态变为 LOADED，之后数据集便可开始接受查询和更新（如果有）。

注意 ：请确保项目对 dataSources 具有适当的读取权限。 否则，编入索引将失败并显示 PERMISSION_DENIED 或 NOT_FOUND。

查询数据集

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

请求会立即返回，并且数据集不会接受其他查询或更新。数据可能要过一段时间才能完全移除 从服务中移除，之后列出数据集不会返回此数据集。

后续步骤

• Timeseries Insights API 概念
• 详细了解 REST API

您可在以下位置找到其他一些示例： GDELT 网站：搜索“Timeseries” Insights API”。