**终止支持通知：** AWS 将于 2026 年 10 月 30 日终止对亚马逊 Pinpoint 的支持。2026 年 10 月 30 日之后，您将不再能够访问 Amazon Pinpoint 控制台或 Amazon Pinpoint 资源（端点、分段、活动、旅程和分析）。有关更多信息，请参阅 [Amazon Pinpoint 终止支持](https://docs.aws.amazon.com/console/pinpoint/migration-guide)。**注意：** APIs 与短信相关、语音、移动推送、OTP 和电话号码验证不受此更改的影响，并受 AWS 最终用户消息的支持。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 Amazon Pinpoint 分析 JSON 查询结果
当您使用亚马逊 Pinpoint Analytics 查询分析 APIs 数据时，亚马逊 Pinpoint 会以 JSON 响应的形式返回结果。对于应用程序指标、活动指标和旅程参与指标，响应中的数据采用标准 JSON 架构来报告 Amazon Pinpoint 分析数据。
这意味着，您可以使用所选的编程语言或工具实施自定义解决方案，以查询一个或多个指标的数据，捕获每个查询的结果，然后将结果写入到表、对象或其他位置。随后，您可以使用其他服务或应用程序在该位置处理查询结果。
例如，您可以：
+ 使用首选的数据可视化框架构建一个自定义控制面板来定期查询一组指标并显示结果。
+ 通过查询适当的指标并在图表或您设计的其他类型的报告中显示结果来创建跟踪参与率的报告。
+ 解析分析数据并将其写入特定的存储格式，然后将结果移植到长期存储解决方案。
请注意，亚马逊 Pinpoint Analytics APIs 并不是为创建或存储任何永久性对象而设计的，您可以随后在亚马逊 Pinpoint 项目或亚马逊 Pinpoint 账户中读取或使用这些对象。相反， APIs 它们旨在帮助您检索分析数据并将该数据传输到其他服务和应用程序以进行进一步分析、存储或报告。为此，对于可通过编程方式为应用程序指标、活动指标和旅程参与指标查询的所有分析数据，它们会使用相同的 JSON 响应结构和架构。
本主题介绍了应用程序指标、活动指标或旅程参与指标查询的 JSON 响应中的结构、对象和字段。有关旅程执行指标或旅程活动执行指标查询的 JSON 响应中的字段的信息，请参阅[适用于 Amazon Pinpoint 项目、活动和旅程的标准指标](analytics-standard-metrics.md)。
## JSON 结构
为了帮助您解析和使用查询结果，Amazon Pinpoint APIs Analytics 对所有亚马逊 Pinpoint 分析数据使用相同的 JSON 响应结构，您可以通过编程方式查询这些数据以获取应用程序指标、活动指标和旅程参与度指标。每个 JSON 响应指定定义查询的值，例如项目 ID (`ApplicationId`)。响应还包括一个（并且只有一个）`KpiResult` 对象。`KpiResult` 对象包含查询的整个结果集。
每个 `KpiResult` 对象包含一个 `Rows` 对象。这是一个对象数组，其中包含查询结果以及有关这些结果中的值的相关元数据。`Rows` 对象的结构和内容具有以下一般特性：
+ 每行查询结果均为 `Rows` 对象中的一个名为 `Values` 的单独的 JSON 对象。例如，如果查询返回三个值，则 `Rows` 对象包含三个 `Values` 对象。每个 `Values` 对象包含单独的查询结果。
+ 每列查询结果均为其应用于的 `Values` 对象的属性。列的名称存储在 `Values` 对象的 `Key` 字段中。
+ 对于分组的查询结果，每个 `Values` 对象均有一个关联的 `GroupedBys` 对象。`GroupedBys` 对象指示使用哪个字段对结果进行分组。它还提供了关联的 `Values` 对象的分组值。
+ 如果指标的查询结果为 null，则 `Rows` 对象为空。
除了这些一般特性之外，`Rows` 对象的结构和内容因指标而异。这是因为 Amazon Pinpoint 支持两种指标，即*单值指标*和*多值指标*。
*单值指标* 仅提供一个累积值。例如，对于某个活动的所有运行，送达收件人的消息的百分比。*多值指标* 提供多个值，并按相关字段对这些值进行分组。例如，按活动运行分组，对于活动的每个运行，送达收件人的消息的百分比。
可从指标名称快速判断出指标是单值指标还是多值指标。如果指标名称不包含 `grouped-by`，则是单值指标。如果包含，则是多值指标。有关可通过编程方式查询的指标的完整列表，请参阅[适用于 Amazon Pinpoint 项目、活动和旅程的标准指标](analytics-standard-metrics.md)。
### 单值指标
对于单值指标，`Rows` 对象包含一个 `Values` 对象，用于：
+ 指定已查询的指标的友好名称。
+ 提供已查询的指标的值。
+ 标识已返回的值的数据类型。
例如，以下 JSON 响应包含一个单值指标的查询结果。该指标报告从 2019 年 8 月 1 日到 2019 年 8 月 31 日，对于与某个项目关联的所有活动，消息送达到的唯一端点数量：
```
{
"ApplicationDateRangeKpiResponse":{
"ApplicationId":"1234567890123456789012345example",
"EndTime":"2019-08-31T23:59:59Z",
"KpiName":"unique-deliveries",
"KpiResult":{
"Rows":[
{
"Values":[
{
"Key":"UniqueDeliveries",
"Type":"Double",
"Value":"1368.0"
}
]
}
]
},
"StartTime":"2019-08-01T00:00:00Z"
}
}
```
在该示例中，响应显示从 2019 年 8 月 1 日到 2019 年 8 月 31 日，该项目的所有活动向 1,368 个唯一端点送达了消息，其中：
+ `Key` 是其值在 `Value` 字段中指定的指标的友好名称（此处为 `UniqueDeliveries`）。
+ `Type` 是在 `Value` 字段中指定的值的数据类型（此处为 `Double`）。
+ `Value` 是所查询指标的实际值，包括应用的任何筛选器（此处为 `1368.0`）。
如果单值指标的查询结果为 null（不大于或等于零），则 `Rows` 对象为空。如果某个指标没有任何数据可返回，则 Amazon Pinpoint 对于该指标返回 null 值。例如：
```
{
"ApplicationDateRangeKpiResponse":{
"ApplicationId":"2345678901234567890123456example",
"EndTime":"2019-08-31T23:59:59Z",
"KpiName":"unique-deliveries",
"KpiResult":{
"Rows":[
]
},
"StartTime":"2019-08-01T00:00:00Z"
}
}
```
### 多值指标
多值指标的 `Rows` 对象的结构和内容与单值指标的大致相同。多值指标的 `Rows` 对象还包含一个 `Values` 对象。`Values` 对象指定查询的指标的友好名称，提供该指标的值，并指定该值的数据类型。
不过，多值指标的 `Rows` 对象还包含一个或多个 `GroupedBy` 对象。在查询结果中，每个 `Values` 对象均有一个对应的 `GroupedBy` 对象。`GroupedBy` 对象指示使用哪个字段对结果中的数据进行分组以及该字段的数据类型。它还指示该字段的分组值（对于关联的 `Values` 对象）。
例如，以下 JSON 响应包含一个多值指标的查询结果，该指标报告从 2019 年 8 月 1 日至 2019 年 8 月 31 日，对于与某个项目关联的每个活动，消息送达的唯一端点的数量：
```
{
"ApplicationDateRangeKpiResponse":{
"ApplicationId":"1234567890123456789012345example",
"EndTime":"2019-08-31T23:59:59Z",
"KpiName":"unique-deliveries-grouped-by-campaign",
"KpiResult":{
"Rows":[
{
"GroupedBys":[
{
"Key":"CampaignId",
"Type":"String",
"Value":"80b8efd84042ff8d9c96ce2f8example"
}
],
"Values":[
{
"Key":"UniqueDeliveries",
"Type":"Double",
"Value":"123.0"
}
]
},
{
"GroupedBys":[
{
"Key":"CampaignId",
"Type":"String",
"Value":"810c7aab86d42fb2b56c8c966example"
}
],
"Values":[
{
"Key":"UniqueDeliveries",
"Type":"Double",
"Value":"456.0"
}
]
},
{
"GroupedBys":[
{
"Key":"CampaignId",
"Type":"String",
"Value":"42d8c7eb0990a57ba1d5476a3example"
}
],
"Values":[
{
"Key":"UniqueDeliveries",
"Type":"Double",
"Value":"789.0"
}
]
}
]
},
"StartTime":"2019-08-01T00:00:00Z"
}
}
```
在此示例中，响应显示从 2019 年 8 月 1 日至 2019 年 8 月 31 日，有三个项目活动向唯一端点送达了消息。对于其中的每个活动，送达计数具体为：
+ 活动 `80b8efd84042ff8d9c96ce2f8example` 将消息送达 123 个唯一端点。
+ 活动 `810c7aab86d42fb2b56c8c966example` 将消息送达 456 个唯一端点。
+ 活动 `42d8c7eb0990a57ba1d5476a3example` 将消息送达 789 个唯一端点。
其中，对象和字段的一般结构为：
+ `GroupedBys.Key` – 存储在 `GroupedBys.Value` 字段中指定的分组值的属性或字段的名称（此处为 `CampaignId`）。
+ `GroupedBys.Type` – 在 `GroupedBys.Value` 字段中指定的值的数据类型（此处为 `String`）。
+ `GroupedBys.Value` – 用于分组数据的字段的实际值，如 `GroupedBys.Key` 字段中指定的（活动 ID）。
+ `Values.Key` – 其值在 `Values.Value` 字段中指定的指标的友好名称（此处为 `UniqueDeliveries`）。
+ `Values.Type` – 在 `Values.Value` 字段中指定的值的数据类型（此处为 `Double`）。
+ `Values.Value` – 所查询指标的实际值，包括应用的任何筛选器。
如果特定项目、活动或其他资源的多值指标的查询结果为 null（不大于或等于零），则 Amazon Pinpoint 不会为该资源返回任何对象或字段。如果对于所有资源，某个多值指标的查询结果为 null，则 Amazon Pinpoint 返回一个空 `Rows` 对象。
## JSON 对象和字段
除了指定定义查询的值（例如项目 ID (`ApplicationId`)）以外，应用程序指标、活动指标或旅程参与指标查询的每个 JSON 响应还包含一个 `KpiResult` 对象。此对象包含查询的整个结果集，可以分析该结果集以将分析数据发送到其他服务或应用程序。根据指标，每个 `KpiResult` 对象均包含以下部分或全部标准对象和字段。
| 对象或字段 | 说明 |
| --- | --- |
| Rows | 包含查询的结果集的对象数组。 |
| Rows.GroupedBys | 对于多值指标，为一个字段数组，用于定义已用于对查询结果中的数据进行分组的字段和值。 |
| Rows.GroupedBys.Key | 对于多值指标，为用于存储 GroupedBys.Value 字段中指定的值的属性或字段的名称。 |
| Rows.GroupedBys.Type | 对于多值指标，为 GroupedBys.Value 字段中指定的值的数据类型。 |
| Rows.GroupedBys.Value | 对于多值指标，为已用于对查询结果中的数据进行分组的字段的实际值。此值与关联的 Values 对象相关。 |
| Rows.Values | 一个包含查询结果的字段数组。 |
| Rows.Values.Key | 查询的指标的友好名称。指标的值是在 Values.Value 字段中指定的。 |
| Rows.Values.Type | Values.Value 字段中指定的值的数据类型。 |
| Rows.Values.Value | 所查询指标的实际值，包括应用的任何筛选器。 |
有关旅程执行指标或旅程活动执行指标查询的 JSON 响应中的字段的信息，请参阅[适用于 Amazon Pinpoint 项目、活动和旅程的标准指标](analytics-standard-metrics.md)。