**终止支持通知：** 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 分析数据 除了使用 Amazon Pinpoint 控制台上的分析页面外，您还可以使用 Amazon Pinpoint APIs Analytics 来查询分析数据，了解一部分标准指标，这些指标可以深入了解与用户参与度、活动推广等相关的趋势。这些指标，也称为*关键绩效指标 (KPIs)*，是可衡量的值，可以帮助您监控和评估项目、活动和旅程的绩效。 如果您使用查询分析数据，则可以使用自己选择的报告工具来分析数据，而无需登录 Amazon Pinpoint 控制台或分析来自 Amazon Kinesis 流等来源的原始事件数据。 APIs 例如，您可以构建一个自定义控制面板，来显示每周活动成果或提供活动送达率的深度分析数据。 您可以使用 Amazon Pinpoint REST API、 AWS Command Line Interface (AWS CLI) 或软件开发工具包查询数据。 AWS 要查询数据，请向 Amazon Pinpoint API 发送请求，并使用支持的参数指定您所需的数据以及要应用的任何筛选器。提交查询后，Amazon Pinpoint 在 JSON 响应中返回查询结果。然后，您可以将这些结果传递到其他服务或应用程序，以便进行更深入的分析、存储或报告。 Amazon Pinpoint 自动为所有项目、活动和旅程收集和聚合所有受支持指标的数据。此外，由于这些数据不断更新，导致数据延迟，但延迟时间限于约两小时内。但要注意，某些指标可能具有更长时间的数据延迟。这是因为，某些指标的数据基于我们从收件人的电子邮件提供商那里收到的信息。一些提供商会立即向我们发送此类信息，而另一些提供商可能不会这么快地向我们发送信息。 Amazon Pinpoint 将这些数据存储 90 天。要想将数据存储 90 天以上或实时访问原始分析数据，您可以配置 Amazon Pinpoint 项目以将事件数据流式流传输到 Amazon Kinesis Data Streams 或 Amazon Data Firehose。有关配置事件流的信息，请参阅[使用 Amazon Pinpoint 通过 Kinesis 和 Firehose 流式传输应用程序事件数据](event-streams.md)。 ## 在 Amazon Pinpoint 中查询指标的组件和参数 要查询指标的数据，您可以将 `get` 请求发送到 Amazon Pinpoint API 的相应指标资源。在您的请求中，您可以使用以下查询组件的受支持参数来定义查询： + **项目** – 通过提供项目 ID 作为 `application-id` 参数的值来指定项目。此参数是所有指标的必需参数。 + **活动** – 通过提供活动 ID 作为 `campaign-id` 参数的值来指定活动。此参数仅是活动指标的必需参数。 + **旅程** – 通过提供旅程 ID 作为 `journey-id` 参数的值来指定旅程。仅旅程参与和执行指标以及旅程活动执行指标需要使用该参数。 + **旅程活动** – 通过提供旅程活动 ID 作为 `journey-activity-id` 参数的值来指定旅程活动。仅旅程活动执行指标需要使用该参数。 + **日期范围**（可选）– 要按日期范围筛选数据，请使用支持的开始和结束时间参数来提供日期范围的起始和截止日期和时间。这些值应采用扩展的 ISO 8601 格式，并使用协调世界时 (UTC)，例如，`2019-07-19T20:00:00Z` 表示协调世界时 2019 年 7 月 19 日晚上 8 点。 日期范围是包含性的，必须限制为不超过 31 个日历天。此外，起始日期和时间必须距离当前日期不到 90 天。如果未指定日期范围，则 Amazon Pinpoint 返回前 31 个日历日期间的数据。除了旅程执行指标和旅程活动执行指标以外，所有其他指标均支持日期范围参数。 + **指标** – 通过提供指标名称作为 `kpi-name` 参数的值来指定指标。此值描述了关联的指标并包含两个或两个以上的术语，这些术语由小写字母数字字符组成并由连字符分隔。示例包括 `email-open-rate` 和 `successful-delivery-rate`。除了旅程执行指标和旅程活动执行指标以外，所有其他指标均需要使用该参数。有关受支持的指标及其所用的 `kpi-name` 值的完整列表，请参阅[项目、活动和旅程的标准指标](analytics-standard-metrics.md)。 发送查询后，Amazon Pinpoint 在 JSON 响应中返回查询结果。在响应中，结果的结构因您查询的指标而异。 某些指标仅提供一个值，例如，某个活动送达的消息数。某些指标则提供多个值，并且这些值通常按相关字段进行分组，例如，对于某个活动的每次运行，按活动运行来分组送达的消息数量。如果指标提供多个值并进行分组，则 JSON 响应包括一个字段，以指示使用哪个字段对数据进行分组。要了解有关查询结果结构的更多信息，请参阅[使用 JSON 查询结果](analytics-query-results.md)。 # 有关查询 Amazon Pinpoint 分析数据的 IAM 策略 通过使用 Amazon Pinpoint API，您可以查询分析数据以获取标准指标子集，也称为适用于亚马逊 Pinpoint 项目、活动和旅程的*关键绩效指标 (KPIs)*。这些指标可以帮助您监控和评估项目、活动和旅程的绩效。 要管理对这些数据的访问权限，您可以创建 AWS Identity and Access Management (IAM) 策略，为有权访问这些数据的 IAM 角色或用户定义权限。为帮助精细控制对这些数据的访问，Amazon Pinpoint 提供了几种您可以在 IAM 策略中指定的不同操作。一种操作是在 Amazon Pinpoint 控制台上查看分析数据 (`mobiletargeting:GetReports`)，其他操作还包括使用 Amazon Pinpoint API 以编程方式访问分析数据等。 要创建管理分析数据访问权限的 IAM 策略，您可以使用 AWS 管理控制台 AWS CLI、或 IAM API。请注意， AWS 管理控制台 上的**可视化编辑器**选项卡目前不包含查看或查询 Amazon Pinpoint 分析数据的操作。不过，您可以使用控制台上的 **JSON** 选项卡手动向 IAM 策略添加必要操作。 例如，以下政策允许以编程方式访问您在所有 AWS 地区的所有项目、活动和旅程的所有分析数据： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QueryAllAnalytics", "Effect": "Allow", "Action": [ "mobiletargeting:GetApplicationDateRangeKpi", "mobiletargeting:GetCampaignDateRangeKpi", "mobiletargeting:GetJourneyDateRangeKpi", "mobiletargeting:GetJourneyExecutionMetrics", "mobiletargeting:GetJourneyExecutionActivityMetrics" ], "Resource": [ "arn:aws:mobiletargeting:*:111122223333:apps/*/kpis/*", "arn:aws:mobiletargeting:*:111122223333:apps/*/campaigns/*/kpis/*", "arn:aws:mobiletargeting:*:111122223333:apps/*/journeys/*/kpis/*", "arn:aws:mobiletargeting:*:111122223333:apps/*/journeys/*/execution-metrics", "arn:aws:mobiletargeting:*:111122223333:apps/*/journeys/*/activities/*/execution-metrics" ] } ] } ``` ------ 您的 AWS 账户 ID 在*accountId*哪里。 但作为最佳实践，您应创建遵循*最低权限* 原则的策略。换句话说，您应创建仅包含执行特定任务所需的权限的策略。为了支持这种做法并实现更精细的控制，您可以限制程序只能访问特定 AWS 区域中特定项目的分析数据，例如： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QueryProjectAnalytics", "Effect": "Allow", "Action": [ "mobiletargeting:GetApplicationDateRangeKpi", "mobiletargeting:GetCampaignDateRangeKpi", "mobiletargeting:GetJourneyDateRangeKpi", "mobiletargeting:GetJourneyExecutionMetrics", "mobiletargeting:GetJourneyExecutionActivityMetrics" ], "Resource": [ "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/kpis/*", "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/campaigns/*/kpis/*", "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/*/kpis/*", "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/*/execution-metrics", "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/*/activities/*/execution-metrics" ] } ] } ``` ------ 其中： + *region*是托管该项目的 AWS 区域的名称。 + *accountId*是您的 AWS 账户 ID。 + *projectId*是您要提供访问权限的项目的标识符。 同样，以下策略示例仅允许编程访问特定活动的分析数据： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QueryCampaignAnalytics", "Effect": "Allow", "Action": "mobiletargeting:GetCampaignDateRangeKpi", "Resource": "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/campaigns/campaignId/kpis/*" } ] } ``` ------ 其中： + *region*是托管该项目的 AWS 区域的名称。 + *accountId*是你的 AWS 账户 身份证。 + *projectId*是与活动关联的项目的标识符。 + *campaignId*是您要提供访问权限的广告系列的标识符。 以下策略示例允许编程访问特定旅程和构成该旅程的活动的所有分析数据，包括参与度和执行数据： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "QueryJourneyAnalytics", "Effect": "Allow", "Action": [ "mobiletargeting:GetJourneyDateRangeKpi", "mobiletargeting:GetJourneyExecutionMetrics", "mobiletargeting:GetJourneyExecutionActivityMetrics" ], "Resource": [ "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/journeyId/kpis/*", "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/journeyId/execution-metrics", "arn:aws:mobiletargeting:us-east-1:111122223333:apps/projectId/journeys/journeyId/activities/*/execution-metrics" ] } ] } ``` ------ 其中： + *region*是托管该项目的 AWS 区域的名称。 + *accountId*是您的 AWS 账户 ID。 + *projectId*是与旅程关联的项目的标识符。 + *journeyId*是您要提供访问权限的旅程的标识符。 有关您可以在 IAM 策略中使用的 Amazon Pinpoint API 操作的完整列表，请参阅[用于 IAM 策略的 Amazon Pinpoint 操作](permissions-actions.md)。有关创建和管理 IAM 策略的详细信息，请参阅 [IAM 用户指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/)。 # 适用于 Amazon Pinpoint 项目、活动和旅程的标准指标 您可以使用亚马逊 Pinpoint Analytics APIs 来查询适用于亚马逊 Pinpoint 项目、活动和旅程的标准指标子集的分析数据。这些指标，也称为*关键绩效指标 (KPIs)*，是可衡量的值，可以帮助您监控和评估项目、活动和旅程的绩效。 Amazon Pinpoint 提供对于以下几种标准指标的分析数据的编程访问： + **应用程序指标** – 通过这些指标可以了解与项目（也称为*应用程序*）相关的所有活动和事务性消息的趋势。例如，您可以使用应用程序指标了解为项目的各个相关活动发送的消息中，具体有多少被收件人打开。 + **活动指标** – 通过这些指标可了解单个活动的绩效。例如，您可以使用活动指标来确定已向多少个端点发送活动消息，或者其中有多少消息送达端点。 + **旅程参与指标** – 通过这些指标可以了解各个旅程的绩效。例如，您可以使用旅程参与指标获取在旅程的每个活动中，参与者打开消息的数量的明细。 + **旅程执行指标** – 通过这些指标可以了解各个旅程的参与趋势。例如，您可以使用旅程执行指标确定有多少个参与者启动了旅程。 + **旅程活动执行指标** – 通过这些指标可以了解旅程中的各个活动的参与趋势。例如，您可以使用旅程活动执行指标确定有多少个参与者启动了活动，以及有多少参与者完成了活动中的每个路径。 此部分中的主题列出并描述了每种指标类型可查询的各个指标。 **Topics** + [Amazon Pinpoint 活动的应用程序指标](application-metrics-campaigns.md) + [事务性电子邮件消息的 Amazon Pinpoint 应用程序指标](application-metrics-txn-email.md) + [事务性短信的 Amazon Pinpoint 应用程序指标](application-metrics-txn-sms.md) + [Amazon Pinpoint 活动指标](campaign-metrics.md) + [Amazon Pinpoint 旅程参与指标](journey-metrics-engagement-email.md) + [Amazon Pinpoint 旅程执行指标](journey-metrics-execution.md) + [Amazon Pinpoint 旅程活动执行指标](journey-metrics-activity-execution.md) + [Amazon Pinpoint 旅程和活动执行指标](journey-run-metrics-activity-execution.md) # Amazon Pinpoint 活动的应用程序指标 下表列出并描述了有关活动的标准应用程序指标，您可以查询这些指标来评估与 Amazon Pinpoint 项目相关的所有活动的绩效。要查询这些指标的数据，请使用 Amazon Pinpoint API 的[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html)资源。该表中的 **kpi-name** 列表示查询中的 `kpi-name` 参数所用的值。 | 指标 | Kpi-name | 说明 | | --- | --- | --- | | 送达率 | `successful-delivery-rate` | 对于项目相关的所有活动，已送达收件人的消息的百分比。 此指标的计算方式为：项目的所有活动已发送并且已送达收件人的消息的数量，除以所有这些活动已发送的消息的数量。 | | 按日期分组的送达率 | `successful-delivery-rate-grouped-by-date` | 对于项目相关的所有活动，在指定日期范围内的每一天已送达收件人的消息的百分比。 此指标的计算方式为：在指定日期范围内的每一天，项目的所有活动发送的并且已送达收件人的消息的数量，除以所有这些活动发送的消息的数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 电子邮件打开率 | `email-open-rate` | 对于项目相关的所有活动，收件人打开的电子邮件的百分比。 此指标的计算方式为：项目的所有活动发送的并且收件人打开的电子邮件的数量，除以所有这些活动发送的并且已送达收件人的电子邮件的数量。 | | 按活动分组的电子邮件打开率 | `email-open-rate-grouped-by-campaign` | 对于项目相关的每个活动，收件人打开的电子邮件的百分比。 此指标的计算方式为：某个活动发送的并且收件人打开的电子邮件的数量，除以此活动发送的并且已送达收件人的电子邮件的数量。 此指标的查询结果按活动 ID (`CampaignId`) 分组，这是一个可唯一识别活动的字符串。 | | 端点送达数 | `unique-deliveries` | 对于项目相关的所有活动，消息送达的唯一端点数量。 | | 按活动分组的端点送达数 | `unique-deliveries-grouped-by-campaign` | 对于项目相关的每个活动，消息送达的唯一端点数量。 此指标的查询结果按活动 ID (`CampaignId`) 分组，这是一个可唯一识别活动的字符串。 | | 按日期分组的端点送达数 | `unique-deliveries-grouped-by-date` | 对于项目相关的所有活动，在指定日期范围内的每一天消息送达的唯一端点数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 按活动分组的已送达消息数 | `successful-deliveries-grouped-by-campaign` | 对于项目相关的每个活动，送达收件人的消息的数量。 此指标的计算方式为：某个活动发送的消息数量，减去此活动发送的但因硬退信而无法送达收件人的消息数量。 此指标的查询结果按活动 ID (`CampaignId`) 分组，这是一个可唯一识别活动的字符串。 | | Push open rate (推送通知打开率) | `push-open-rate` | 对于项目相关的所有活动，收件人打开的推送通知百分比。 此指标的计算方式为：项目的所有活动发送的并且收件人打开的推送通知数量，除以所有这些活动发送并送达到收件人的推送通知数量。 | | 按活动分组的推送通知打开率 | `push-open-rate-grouped-by-campaign` | 对于项目相关的每个活动，收件人打开的推送通知百分比。 此指标的计算方式为：某个活动发送的并且收件人打开的推送通知数量，除以此活动发送并送达到收件人的推送通知数量。 此指标的查询结果按活动 ID (`CampaignId`) 分组，这是一个可唯一识别活动的字符串。 | # 事务性电子邮件消息的 Amazon Pinpoint 应用程序指标 下表列出并描述了有关事务性电子邮件消息的标准应用程序指标，您可以查询这些指标来监控与 Amazon Pinpoint 项目相关的所有事务性电子邮件消息的趋势。要查询这些指标的数据，请使用 Amazon Pinpoint API 的[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html)资源。该表中的 **kpi-name** 列表示查询中的 `kpi-name` 参数所用的值。 请注意，这些指标不提供关于活动所发送的电子邮件消息的数据。它们仅提供有关事务性电子邮件消息的数据。要查询一个或多个活动所发送的消息的数据，请使用[活动指标](campaign-metrics.md)或[活动应用程序指标](application-metrics-campaigns.md)。 | 指标 | Kpi-name | 说明 | | --- | --- | --- | | 点击次数 | `txn-emails-clicked` | 收件人点击消息中的链接的次数。如果一个收件人单击了一封邮件中的多个链接，或多次单击同一链接，则每次单击均包含在该计数中。 | | 按日期分组的点击次数 | `txn-emails-clicked-grouped-by-date` | 在指定日期范围内的每一天，收件人点击消息中链接的次数。如果一个收件人单击了一封邮件中的多个链接，或多次单击同一链接，则每次单击均包含在该计数中。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 投诉率 | `txn-emails-complaint-rate` | 收件人报告的未经请求或不需要的电子邮件所占的百分比。 该指标的计算方法为：收件人报告的未经请求或不需要的电子邮件的数量除以已发送邮件的数量。 | | 按日期分组的投诉率 | `txn-emails-complaint-rate-grouped-by-date` | 在指定日期范围内的每一天，收件人报告的未经请求或不需要的电子邮件所占的百分比。 该指标的计算方法为：在指定日期范围内的每一天，收件人报告的未经请求或不需要的电子邮件的数量除以已发送邮件的数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 投诉数 | `txn-emails-with-complaints` | 收件人报告的未经请求或不需要的电子邮件的数量。 | | 按日期分组的投诉数 | `txn-emails-with-complaints-grouped-by-date` | 在指定日期范围内的每一天，收件人报告的未经请求或不需要的电子邮件的数量。此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 已传送数 | `txn-emails-delivered` | 已送达收件人的邮件的数量。 该指标的计算方法是：发送的消息数减去因软或硬退信或者被拒绝而无法传送的消息数。如果 Amazon Pinpoint 确定消息中包含恶意软件，则该消息将被拒绝。Amazon Pinpoint 不会尝试发送被拒绝的消息。 | | 按日期分组的已传送数 | `txn-emails-delivered-grouped-by-date` | 在指定日期范围内的每一天，已送达收件人的邮件的数量。 此指标的计算方法为：在指定日期范围内的每一天，已发送消息的数量减去因软或硬退信或者被拒绝而无法传送的消息数。如果 Amazon Pinpoint 确定消息中包含恶意软件，则该消息将被拒绝。Amazon Pinpoint 不会尝试发送被拒绝的消息。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 送达率 | `txn-emails-delivery-rate` | 已送达收件人的消息所占的百分比。 此指标的计算方法为：已发送并且已送达收件人的消息的数量除以已发送消息的数量。 | | 按日期分组的送达率 | `txn-emails-delivery-rate-grouped-by-date` | 在指定日期范围内的每一天，已送达收件人的消息所占的百分比。 此指标的计算方法为：在指定日期范围内的每一天，已发送并且已送达收件人的消息的数量除以已发送消息的数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 硬退信数 | `txn-emails-hard-bounced` | 因硬退信而导致无法送达收件人的消息的数量。如果因持久性问题（例如，收件人的电子邮件地址不存在）导致邮件无法送达，会造成硬退信。 | | 按日期分组的硬退信数 | `txn-emails-hard-bounced-grouped-by-date` | 在指定日期范围内的每一天，因硬退信而导致无法送达收件人的消息的数量。如果因持久性问题（例如，收件人的电子邮件地址不存在）导致邮件无法送达，会造成硬退信。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 打开 | `txn-emails-opened` | 收件人打开的消息的数量。 | | 按日期分组的打开次数 | `txn-emails-opened-grouped-by-date` | 在指定日期范围内的每一天，收件人打开的消息的数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 发送 | `txn-emails-sent` | 发送的消息的数量。 | | 按日期分组的发送数 | `txn-emails-sent-grouped-by-date` | 在指定日期范围内的每一天发送的邮件的数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 软退信数 | `txn-emails-soft-bounced` | 因软退信导致无法送达收件人的消息的数量。如果因临时性问题（例如收件人的收件箱已满或接收服务器暂时不可用）导致邮件无法送达，会造成软退信。 | | 按日期分组的软退信数 | `txn-emails-soft-bounced-grouped-by-date` | 在指定日期范围内的每一天，因软退信导致无法送达收件人的消息的数量。如果因临时性问题（例如收件人的收件箱已满或接收服务器暂时不可用）导致邮件无法送达，会造成软退信。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 唯一用户点击事件 | `txn-emails-unique-clicks` | 点击消息中链接的唯一收件人（端点）的数量。 与**点击次数**指标不同，该指标报告的是点击链接的唯一收件人的数量，而不是发生的点击事件的次数。例如，如果一个收件人单击了同一邮件中的多个链接，或多次单击同一个链接，该指标报告为该收件人只有一个单击事件。 | | 按日期分组的唯一用户点击事件 | `txn-emails-unique-clicks-grouped-by-date` | 在指定日期范围内的每一天，点击消息中链接的唯一收件人（端点）的数量。 与**按日期分组的点击次数**指标不同，该指标报告的是点击链接的唯一收件人的数量，而不是发生的点击事件的次数。例如，如果一个收件人单击了同一邮件中的多个链接，或多次单击同一个链接，该指标报告为该收件人只有一个单击事件。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 唯一用户打开事件 | `txn-emails-unique-opens` | 打开消息的唯一收件人（端点）的数量。 与**打开次数**指标不同，该指标报告的是打开消息的唯一收件人的数量，而不是发生的打开事件的次数。例如，如果一个收件人多次打开同一封邮件，该指标报告为该收件人只有一个打开事件。 | | 按日期分组的唯一用户打开事件 | `txn-emails-unique-opens-grouped-by-date` | 在指定日期范围内的每一天，打开消息的唯一收件人（端点）的数量。 与**按日期分组的打开次数**指标不同，该指标报告的是打开消息的唯一收件人的数量，而不是发生的打开事件的次数。例如，如果一个收件人多次打开同一封邮件，该指标报告为该收件人只有一个打开事件。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | # 事务性短信的 Amazon Pinpoint 应用程序指标 下表列出并描述了有关事务性短信的标准应用程序指标，您可以查询这些指标来了解与 Amazon Pinpoint 项目相关的所有事务性短信的趋势。要查询这些指标的数据，请使用 Amazon Pinpoint API 的[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html)资源。该表中的 **kpi-name** 列表示查询中的 `kpi-name` 参数所用的值。 请注意，这些指标不提供有关活动发送的短信的数据。它们仅提供有关事务性短信的数据。要查询一个或多个活动所发送的消息的数据，请使用[活动指标](campaign-metrics.md)或[活动应用程序指标](application-metrics-campaigns.md)。 | 指标 | Kpi-name | 说明 | | --- | --- | --- | | 按国家/地区分组的每消息平均价格 | `txn-sms-average-price-grouped-by-country` | 对于消息发往的每个国家或地区，发送每个消息的平均成本。价格单位为千分之一美分。例如，如果此属性的值为 645，则我们收取的消息发送单价是 0.645¢ (645 / 1000 = 0.645¢ = \$10.00645)。 此指标的计算方式是：发送给某个国家或地区的收件人的所有消息的总成本除以发送给该国家或地区的收件人的消息数。 此指标的查询结果按国家或地区分组，采用 ISO 3166-1 alpha-2 格式。 | | 按国家/地区分组的每消息部分的平均价格 | `txn-sms-average-price-by-parts-grouped-by-country` | 对于消息发往的每个国家或地区，发送每个消息部分的平均成本。消息部分是短信的一部分。价格单位为千分之一美分。例如，如果此属性的值为 645，则我们收取的消息发送单价是 0.645¢ (645 / 1000 = 0.645¢ = \$10.00645)。 此指标的计算方式是：发送给某个国家或地区的收件人的所有消息部分的总成本除以发送给该国家或地区的收件人的消息部分数。 此指标的查询结果按国家或地区分组，采用 ISO 3166-1 alpha-2 格式。 | | 已传送数 | `txn-sms-delivered` | 已送达收件人的邮件的数量。 | | 按国家/地区分组的已送达数 | `txn-sms-delivered-grouped-by-country` | 对于消息发往的每个国家或地区，已送达收件人的消息数量。 此指标的查询结果按国家或地区分组，采用 ISO 3166-1 alpha-2 格式。 | | 按日期分组的已传送数 | `txn-sms-delivered-grouped-by-date` | 在指定日期范围内的每一天，已送达收件人的邮件的数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 传输错误数 | `txn-sms-error-distribution` | 传输消息时发生的各种错误的次数。 此指标的查询结果针对发生的每种类型的错误按错误代码来分组。 | | 送达率 | `txn-sms-delivery-rate` | 已送达收件人的消息所占的百分比。 此指标的计算方法为：已发送并且已送达收件人的消息的数量除以已发送消息的数量。 | | 按日期分组的送达率 | `txn-sms-delivery-rate-grouped-by-date` | 在指定日期范围内的每一天，已送达收件人的消息所占的百分比。 此指标的计算方法为：在指定日期范围内的每一天，已发送并且已送达收件人的消息的数量除以已发送消息的数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 消息部分已送达数 | `txn-sms-delivered-by-parts` | 已送达的消息部分数。*消息部分* 是短信的一部分。如果短信包含的字符数超过短信协议允许的字符数，Amazon Pinpoint 会根据需要将消息拆分为若干消息部分，以便将消息发送给收件人。 | | 按国家/地区分组的消息部分已送达数 | `txn-sms-delivered-by-parts-grouped-by-country` | 对于消息发往的每个国家或地区，已送达收件人的消息部分数量。*消息部分* 是短信的一部分。 此指标的查询结果按国家或地区分组，采用 ISO 3166-1 alpha-2 格式。 | | 消息部分已发送数 | `txn-sms-sent-by-parts` | 发送的消息部分的数量。*消息部分* 是短信的一部分。如果短信包含的字符数超过短信协议允许的字符数，Amazon Pinpoint 会根据需要将消息拆分为若干消息部分，以便将消息发送给收件人。 | | 按国家/地区分组的已发送的消息部分数 | `txn-sms-sent-by-parts-grouped-by-country` | 对于消息发往的每个国家或地区，已发送的消息部分数量。*消息部分* 是短信的一部分。 此指标的查询结果按国家或地区分组，采用 ISO 3166-1 alpha-2 格式。 | | 发送的消息数 | `txn-sms-sent` | 发送的消息的数量。 | | 按国家/地区分组的已发送的消息数 | `txn-sms-sent-grouped-by-country` | 对于消息发往的每个国家或地区，已发送的消息数量。 此指标的查询结果按国家或地区分组，采用 ISO 3166-1 alpha-2 格式。 | | 按日期分组的已发送的消息数 | `txn-sms-sent-grouped-by-date` | 在指定日期范围内的每一天发送的邮件的数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 按国家/地区分组的总价格 | `txn-sms-total-price-grouped-by-country` | 对于消息发往的每个国家或地区，发送的消息的总成本。价格单位为千分之一美分。例如，如果此属性的值为 645，则我们收取的消息发送单价是 0.645¢ (645 / 1000 = 0.645¢ = \$10.00645)。 此指标的查询结果按国家或地区分组，采用 ISO 3166-1 alpha-2 格式。 | # Amazon Pinpoint 活动指标 下表列出并描述了标准活动指标，您可以查询这些指标来评估单个活动的绩效。要查询这些指标的数据，请使用 Amazon Pinpoint API 的[活动指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html)资源。该表中的 **kpi-name** 列表示查询中的 `kpi-name` 参数所用的值。 | 指标 | Kpi-name | 说明 | | --- | --- | --- | | 退回邮件率 | `hard-bounce-rate` | 对于所有活动运行，无法送达收件人的电子邮件的百分比。此指标仅用于衡量硬退信，即，邮件的收件人电子邮件地址存在永久性的问题，使得邮件无法送达。 此指标的计算方式为：所有活动运行发送的但被退回的电子邮件的数量，除以所有这些活动运行发送的电子邮件的数量。 | | 按活动运行分组的退回邮件率 | `hard-bounce-rate-grouped-by-campaign-activity` | 对于每个活动运行，无法送达收件人的电子邮件的百分比。此指标仅用于衡量硬退信，即，邮件的收件人电子邮件地址存在永久性的问题，使得邮件无法送达。 此指标的计算方式为：某个活动运行发送的但被退回的电子邮件的数量，除以该活动运行发送的电子邮件的数量。 此指标的查询结果按活动 ID (`CampaignActivityId`) 分组，这是一个可唯一识别活动运行的字符串。 | | 送达率 | `successful-delivery-rate` | 对于所有活动运行，已送达收件人的消息的百分比。 此指标的计算方式为：所有活动运行发送的并且已送达收件人的消息的数量，除以所有这些活动运行发送的消息的数量。 | | 按活动运行分组的送达率 | `successful-delivery-rate-grouped-by-campaign-activity` | 对于每个活动运行，送达收件人的消息的百分比。 此指标的计算方式为：某个活动运行发送的并且已送达收件人的消息的数量，除以此活动运行发送的消息的数量。 此指标的查询结果按活动 ID (`CampaignActivityId`) 分组，这是一个可唯一识别活动运行的字符串。 | | 按日期分组的送达率 | `successful-delivery-rate-grouped-by-date` | 对于所有活动运行，在指定日期范围内的每一天已送达收件人的消息的百分比。 此指标的计算方式为：在指定日期范围内的每一天，所有活动运行发送的并且已送达收件人的消息的数量，除以所有这些活动运行发送的消息的数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 电子邮件打开率 | `email-open-rate` | 对于所有活动运行，收件人已打开的电子邮件的百分比。此指标的计算方式为：所有活动运行发送的并且收件人打开的电子邮件的数量，除以所有这些活动运行发送的并且已送达收件人的电子邮件的数量。 | | 按活动运行分组的电子邮件打开率 | `email-open-rate-grouped-by-campaign-activity` | 对于每个活动运行，收件人已打开的电子邮件的百分比。 此指标的计算方式为：某个活动运行发送的并且收件人打开的电子邮件的数量，除以此活动运行发送的并且已送达收件人的电子邮件的数量。 此指标的查询结果按活动 ID (`CampaignActivityId`) 分组，这是一个可唯一识别活动运行的字符串。 | | 按活动运行分组的已打开电子邮件数 | `direct-email-opens-grouped-by-campaign-activity` | 对于每个活动运行，收件人已打开的电子邮件的数量。 此指标的查询结果按活动 ID (`CampaignActivityId`) 分组，这是一个可唯一识别活动运行的字符串。 | | 端点送达数 | `unique-deliveries` | 对于所有活动运行，消息送达到的唯一端点数量。 | | 按活动运行分组的端点送达数 | `unique-deliveries-grouped-by-campaign-activity` | 对于每个活动运行，消息送达到的唯一端点数量。 此指标的查询结果按活动 ID (`CampaignActivityId`) 分组，这是一个可唯一识别活动运行的字符串。 | | 按日期分组的端点送达数 | `unique-deliveries-grouped-by-date` | 对于所有活动运行，在指定日期范围内的每一天消息送达到的唯一端点数量。 此指标的查询结果以扩展 ISO 8601 格式按日历日进行分组。 | | 按活动运行分组的已点击链接数 | `clicks-grouped-by-campaign-activity` | 对于每个活动运行，收件人点击电子邮件中的链接的次数。如果一个收件人点击了邮件中的多个链接，或多次点击同一链接，则每次点击均计数。 此指标的查询结果按活动 ID (`CampaignActivityId`) 分组，这是一个可唯一识别活动运行的字符串。 | | 按活动运行分组的已送达消息数 | `successful-deliveries-grouped-by-campaign-activity` | 对于每个活动运行，已送达收件人的消息的数量。 此指标的计算方式为：某个活动运行发送的消息数量，减去因硬退信而无法送达该运行的收件人的消息数量。 此指标的查询结果按活动 ID (`CampaignActivityId`) 分组，这是一个可唯一识别活动运行的字符串。 | | 按活动运行分组的已发送消息数 | `attempted-deliveries-grouped-by-campaign-activity` | 对于每个活动运行，已发送的消息的数量。 此指标的查询结果按活动 ID (`CampaignActivityId`) 分组，这是一个可唯一识别活动运行的字符串。 | | Push open rate (推送通知打开率) | `push-open-rate` | 对于所有活动运行，收件人已打开的推送通知百分比。 此指标的计算方式为：所有活动运行发送的并且收件人打开的推送通知数量，除以所有这些活动运行发送并送达到收件人的推送通知数量。 | | 按活动运行分组的推送通知打开率 | `push-open-rate-grouped-by-campaign-activity` | 对于每个活动运行，收件人已打开的推送通知百分比。 此指标的计算方式为：某个活动运行发送的并且收件人打开的推送通知数量，除以此活动运行发送并送达到收件人的推送通知数量。 此指标的查询结果按活动 ID (`CampaignActivityId`) 分组，这是一个可唯一识别活动运行的字符串。 | | 按活动运行分组的已打开推送通知总数 | `direct-push-opens-grouped-by-campaign-activity` | 对于每个活动运行，收件人已打开的推送通知数量。 此指标的查询结果按活动 ID (`CampaignActivityId`) 分组，这是一个可唯一识别活动运行的字符串。 | | 短信总支出 | sms-spend | 对于所有活动，发送短信的支出总金额（以毫美分为单位）。 | # Amazon Pinpoint 旅程参与指标 下表列出并描述了标准旅程参与指标，您可以查询这些指标以监控 Amazon Pinpoint 旅程发送的所有电子邮件的趋势。要查询这些指标的数据，请使用 Amazon Pinpoint API 的[旅程参与指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-journeys-journey-id-kpis-daterange-kpi-name.html)资源。该表中的 **kpi-name** 列表示查询中的 `kpi-name` 参数所用的值。 | 指标 | Kpi-name | 说明 | | --- | --- | --- | | 点击次数 | `journey-emails-clicked` | 参与者点击消息中的链接的次数。如果一个参与者点击了一个消息中的多个链接，或多次点击同一链接，则每次点击均计数。 | | 按活动分组的点击次数 | `emails-clicked-grouped-by-journey-activity` | 对于旅程中的每个活动，参与者点击消息中的链接的次数。如果一个参与者点击了一个消息中的多个链接，或多次点击同一链接，则每次点击均计数。 该指标的查询结果按活动 ID (`JourneyActivityId`) 进行分组，该 ID 是唯一地标识活动的字符串。 | | 投诉 | `journey-emails-complained` | 参与者报告的未经请求或不需要的电子邮件的数量。 | | 按活动分组的投诉数 | `emails-complained-grouped-by-journey-activity` | 对于旅程中的每个活动，参与者报告的未经请求或不需要的电子邮件的数量。该指标的查询结果按活动 ID (`JourneyActivityId`) 进行分组，该 ID 是唯一地标识活动的字符串。 | | 已传送数 | `journey-emails-delivered` | 已送达参与者的消息数。 该指标的计算方法是：发送的消息数减去由于软或硬退信或者被拒绝而无法传送的消息数。 | | 按活动分组的已送达数 | `emails-delivered-grouped-by-journey-activity` | 对于旅程中的每个活动，送达参与者的消息数。 该指标的计算方式是：对于旅程中的每个活动，发送的消息数减去由于软或硬退信或者被拒绝而无法传送的消息数。 该指标的查询结果按活动 ID (`JourneyActivityId`) 进行分组，该 ID 是唯一地标识活动的字符串。 | | 硬退信数 | `journey-emails-hardbounced` | 由于硬退信而无法传送到参与者的消息数。如果因持久性问题（例如，参与者的电子邮件地址不存在）导致邮件无法送达，会造成硬退信。 | | 按活动分组的硬退信数 | `emails-hardbounced-grouped-by-journey-activity` | 对于旅程中的每个活动，由于硬退信而无法传送到参与者的消息数。如果因持久性问题（例如，参与者的电子邮件地址不存在）导致邮件无法送达，会造成硬退信。 该指标的查询结果按活动 ID (`JourneyActivityId`) 进行分组，该 ID 是唯一地标识活动的字符串。 | | 打开 | `journey-emails-opened` | 参与者打开的消息数。 | | 按活动分组的打开次数 | `emails-opened-grouped-by-journey-activity` | 对于旅程中的每个活动，参与者打开的消息数。 该指标的查询结果按活动 ID (`JourneyActivityId`) 进行分组，该 ID 是唯一地标识活动的字符串。 | | 拒绝数 | `journey-emails-rejected` | 由于被拒绝而未发送到参与者的消息数。如果 Amazon Pinpoint 确定消息中包含恶意软件，则该消息将被拒绝。Amazon Pinpoint 不会尝试发送被拒绝的消息。 | | 按活动分组的拒绝数 | `emails-rejected-grouped-by-journey-activity` | 对于旅程中的每个活动，由于被拒绝而未发送到参与者的消息数。如果 Amazon Pinpoint 确定消息中包含恶意软件，则该消息将被拒绝。Amazon Pinpoint 不会尝试发送被拒绝的消息。 该指标的查询结果按活动 ID (`JourneyActivityId`) 进行分组，该 ID 是唯一地标识活动的字符串。 | | 发送 | `journey-emails-sent` | 发送的消息的数量。 | | 按活动分组的发送数 | `emails-sent-grouped-by-journey-activity` | 对于旅程中的每个活动，发送的消息数。 该指标的查询结果按活动 ID (`JourneyActivityId`) 进行分组，该 ID 是唯一地标识活动的字符串。 | | 软退信数 | `journey-emails-softbounced` | 由于软退信而无法传送到参与者的消息数。如果因临时性问题（例如参与者的收件箱已满或接收服务器暂时不可用）导致邮件无法送达，会造成软退信。 | | 按活动分组的软退信数 | `emails-softbounced-grouped-by-journey-activity` | 对于旅程中的每个活动，由于软退信而无法传送到参与者的消息数。如果因临时性问题（例如参与者的收件箱已满或接收服务器暂时不可用）导致邮件无法送达，会造成软退信。 该指标的查询结果按活动 ID (`JourneyActivityId`) 进行分组，该 ID 是唯一地标识活动的字符串。 | | 取消订阅数 | `journey-emails-unsubscribed` | 参与者点击消息中的取消订阅链接的次数。如果一个参与者多次点击相同的取消订阅链接，则每次点击均计数。 | | 按活动分组的取消订阅数 | `emails-unsubscribed-grouped-by-journey-activity` | 对于旅程中的每个活动，参与者点击消息中的取消订阅链接的次数。如果一个参与者多次点击相同的取消订阅链接，则每次点击均计数。 该指标的查询结果按活动 ID (`JourneyActivityId`) 进行分组，该 ID 是唯一地标识活动的字符串。 | # Amazon Pinpoint 旅程执行指标 下表列出并描述了有关旅程的标准执行指标，您可以查询这些指标以评估 Amazon Pinpoint 旅程中的参与者的状态。要查询这些指标的数据，请使用 Amazon Pinpoint API 的[旅程执行指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-journeys-journey-id-execution-metrics.html)资源。该表中的**字段**列指定在每个指标的查询结果中显示的字段的名称。 | 指标 | 字段 | 说明 | | --- | --- | --- | | 积极参与者数 | `ENDPOINT_ACTIVE` | 积极推进旅程活动的参与者数。 该指标的计算方法是：启动旅程的参与者数，减去离开旅程以及从旅程中删除的参与者数。 | | 参与者取消数 | `CANCELLED` | 因旅程被取消而未完成旅程的参与者数量。 | | 参与者离开数 | `ENDPOINT_LEFT` | 离开旅程的参与者数。 | | 参与者进入数 | `ENDPOINT_ENTERED` | 启动旅程的参与者数。 | | 参与者例外数（超过重新进入限制） | `REENTRY_CAP_EXCEEDED` | 由于超过了单个参与者可以重新进入旅程的最大次数而未完成旅程的参与者数。 | | 参与者例外数（被拒绝） | `ACTIVE_ENDPOINT_REJECTED` | 由于已经是旅程的积极参与者而无法启动旅程的参与者数量。 如果某个参与者启动了一个旅程，而您随后因故更新了其端点定义，影响到其在某个分段（基于分段标准）或该旅程（基于活动条件）中的包含性，则该参与者被拒绝。 | # Amazon Pinpoint 旅程活动执行指标 下表列出并描述了有关旅程活动的标准执行指标，您可以查询这些指标以评估 Amazon Pinpoint 旅程的每种类型的单独活动中的参与者的状态。要查询这些指标的数据，请使用 Amazon Pinpoint API 的[旅程活动执行指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-journeys-journey-id-activities-journey-activity-id-execution-metrics.html)资源。该表中的**指标**列列出在每种类型的活动的查询结果中显示的字段。它还提供了每个字段的简要描述。 | 活动类型 | 指标 | | --- | --- | | 是/否拆分 (`CONDITIONAL_SPLIT`) | 这些指标是： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/pinpoint/latest/developerguide/journey-metrics-activity-execution.html) 活动中每个路径可以使用其他指标。有关这些指标的信息，请参阅该表中与该类型的活动对应的行。 | | 保留 (`HOLDOUT`) | 这些指标是： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/pinpoint/latest/developerguide/journey-metrics-activity-execution.html) | | 电子邮件 (`MESSAGE`) | 这些指标是： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/pinpoint/latest/developerguide/journey-metrics-activity-execution.html) | | 多元拆分 (`MULTI_CONDITIONAL_SPLIT`) | 对于活动的每个路径，在该路径上继续开展活动的参与者数量。 该指标的查询结果按路径分组，`Branch_#`其中*\$1*是路径的数字标识符，例如`Branch_1`活动的第一个路径。 活动中每个路径可以使用其他指标。有关这些指标的信息，请参阅该表中与该类型的活动对应的行。 | | 随机拆分 (`RANDOM_SPLIT`) | 对于活动的每个路径，在该路径上继续开展活动的参与者数量。 该指标的查询结果按路径分组，`Branch_#`其中*\$1*是路径的数字标识符，例如`Branch_1`活动的第一个路径。 活动中每个路径可以使用其他指标。有关这些指标的信息，请参阅该表中与该类型的活动对应的行。 | | 等待 (`WAIT`) | 这些指标是： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/pinpoint/latest/developerguide/journey-metrics-activity-execution.html) | | 联系中心 (`CONTACT_CENTER`) | 这些指标是： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/pinpoint/latest/developerguide/journey-metrics-activity-execution.html) | # Amazon Pinpoint 旅程和活动执行指标 您可以查询这些标准执行指标以评估 Amazon Pinpoint 旅程或活动的每种类型的单独活动中参与者的状态。要查询这些指标的数据，请使用 Amazon Pinpoint API 的[旅程运行活动执行指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-journeys-journey-id-runs-run-id-activities-journey-activity-id-execution-metrics.html)或[活动指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html)资源。下表列出在每种类型的活动的查询结果中显示的字段。 **** | 指标名称 | 适用于旅程和/或活动 | 说明 | | --- | --- | --- | | ENDPOINT\$1PRODUCED | 二者 | 在进行任何筛选之前，最初从分段或事件中生成的端点数量。 | | ENDPOINTS\$1FROM\$1USER | 二者 | 如果客户具有仅用户 ID 分段，则将添加这些用户的所有端点。该指标衡量以此方式添加的端点的数量。 | | ENDPOINT\$1OPT\$1OUT | 二者 | 端点已选择退出且未进入活动或旅程。 | | ENDPOINT\$1INACTIVE | 二者 | 端点处于非活动状态且未进入活动或旅程。 | | FILTERED\$1OUT\$1BY\$1SEGMENT | 二者 | 端点与分段筛选条件不匹配且未进入活动或旅程。 | | ENDPOINT\$1MISSING\$1ADDRESS | 二者 | 端点缺少地址且未进入活动或旅程。 | | ENDPOINT\$1MISSING\$1CHANNEL | 二者 | 端点缺少渠道且未进入活动或旅程。 | | ENDPOINT\$1MISSING\$1TIMEZONE | 二者 | 端点缺少时区值，因此已被过滤掉。只有在需要时区值时才会发生这种情况。 | | ENDPOINT\$1TIMEZONE\$1MISMATCH | 二者 | 端点所在的时区当时未包含在执行中。 | | ENDPOINT\$1CHANNEL\$1MISMATCH | 市场活动 | 活动没有为此端点的渠道类型配置消息。 | | DUPLICATE\$1ENDPOINT | 二者 | 发现了重复的端点并进行了去重。 | | DUPLICATE\$1USER | 二者 | 发现了重复的用户并从仅用户 ID 的分段进行了去重。如果重复用户具有相同的用户 ID，则会发出一个 1 的指标。 | | PAUSED | Journeys | 由于旅程已暂停，所以已从执行中移除。 | | ENDED | Journeys | 由于旅程已结束，所以已从执行中移除。 | | TREATMENT\$1HOLDOUT | 市场活动 | 这是在 A/B 广告系列中针对群组与当前处理方式不匹配的端点发出的。例如，在 50/50 的 A/B 分割中，50% 的终点将针对每次治疗发出此指标 | | ENDPOINT\$1ESTIMATED\$1TIMEZONE | Journeys | 时区估计能够估计端点的时区。 | # 查询活动的 Amazon Pinpoint 分析数据 除了使用 Amazon Pinpoint 控制台上的分析页面外，您还可以使用 Amazon Pinpoint APIs Analytics 来查询分析数据，了解一部分标准指标，这些指标可以深入了解广告活动的投放和参与趋势。 每个指标即是一个可测量的值，也称为*关键绩效指标 (KPI)*，它们可以帮助您监控和评估一个或多个活动的绩效。例如，您可以使用指标来了解活动消息发送给了多少个端点，或者，其中有多少消息送达预期端点。 Amazon Pinpoint 自动为您的所有活动收集并聚合这些数据。它将数据存储 90 天。如果您使用移动软件开发工具包将移动应用程序与 Amazon Pinpoint 集成，Amazon Pinpoint 会将此支持扩展到包括其他指标，例如收件人打开的推送通知的百分比。 AWS 有关集成移动应用程序的信息，请参阅[将 Amazon Pinpoint 与您的应用程序集成](integrate.md)。 如果您使用 Amazon Pinpoint Analytics APIs 来查询数据，则可以选择各种选项来定义查询的范围、数据、分组和筛选条件。除了要应用的任何基于日期的筛选器之外，还可使用参数指定要查询的项目、活动和指标来执行此操作。 本主题提供了有关如何选择这些选项和查询一个或多个活动的数据的示例，并对这些示例进行了说明。 ## 先决条件 在查询一个或多个活动的分析数据之前，收集以下信息很有用，可以用它们来定义查询： + **项目 ID** – 与活动关联的项目的唯一标识符。在 Amazon Pinpoint API 中，此值存储在 `application-id` 属性中。在 Amazon Pinpoint 控制台上，此值在**所有项目**页面上显示为**项目 ID**。 + **活动 ID** – 活动的唯一标识符（如果仅查询一个活动的数据）。在 Amazon Pinpoint API 中，此值存储在 `campaign-id` 属性中。此值不会显示在控制台上。 + **日期范围**（可选）– 设置查询数据的日期范围的起始和截止日期和时间。日期范围是包含性的，必须限制为不超过 31 个日历天。此外，起始时间必须距离当前日期不到 90 天。如果未指定日期范围，Amazon Pinpoint 将自动查询前 31 个日历日期间的数据。 + **指标类型** – 要查询的指标的类型。有两种类型，即*应用程序指标* 和*活动指标*。*应用程序指标* 提供与项目（也称为*应用程序*）关联的所有活动的数据。*活动指标* 仅提供一个活动的数据。 + **指标** – 要查询的指标的名称，更具体地说，即指标的 `kpi-name` 值。有关受支持的指标及其 `kpi-name` 值的完整列表，请参阅[项目、活动和旅程的标准指标](analytics-standard-metrics.md)。 它还可帮助确定是否要按相关字段对数据进行分组。如果您这样做，则可通过选择旨在自动为您对数据进行分组的指标来简化分析和报告。例如，Amazon Pinpoint 提供了多个标准指标来报告已送达活动收件人的邮件的百分比。其中的一个指标自动按日期对数据进行分组 (`successful-delivery-rate-grouped-by-date`)。另一个指标自动按活动运行对数据进行分组 (`successful-delivery-rate-grouped-by-campaign-activity`)。还有一个指标仅返回单个值，即，对于所有活动运行，送达收件人的消息的百分比 (`successful-delivery-rate`)。 如果找不到能以您需要的方式来分组数据的标准指标，您可以开发一系列查询来返回您需要的数据。然后，您可以手动细分或者合并查询结果到您设计的自定义分组中。 最后，请务必确认您有权访问要查询的数据。有关更多信息，请参阅 [有关查询 Amazon Pinpoint 分析数据的 IAM 策略](analytics-permissions.md)。 # 查询一个活动的 Amazon Pinpoint 数据 要查询一个活动的数据，您可以使用[活动指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html) API 并指定以下所需参数的值： + **application-id** – 项目 ID，它是与活动关联的项目的唯一标识符。在 Amazon Pinpoint 中，*项目* 和*应用程序* 具有相同的含义。 + **campaign-id** – 市场活动的唯一标识符。 + **kpi-name** – 要查询的指标的名称。此值描述了关联的指标并包含两个或两个以上的术语，这些术语由小写字母数字字符组成并由连字符分隔。有关受支持的指标及其 `kpi-name` 值的完整列表，请参阅[项目、活动和旅程的标准指标](analytics-standard-metrics.md)。 您也可以应用筛选器来查询特定日期范围的数据。如果未指定日期范围，则 Amazon Pinpoint 返回前 31 个日历日期间的数据。要按不同的日期筛选数据，请使用支持的日期范围参数指定日期范围的起始和截止日期和时间。这些值应采用扩展的 ISO 8601 格式，并使用协调世界时 (UTC)，例如，`2019-07-19T20:00:00Z` 表示协调世界时 2019 年 7 月 19 日晚上 8 点。日期范围是包含性的，必须限制为不超过 31 个日历天。此外，起始日期和时间必须距离当前日期不到 90 天。 以下示例展示了如何使用 Amazon Pinpoint REST API AWS CLI、和，来查询广告活动的分析数据。 适用于 Java 的 AWS SDK您可以使用任何支持的 AWS SDK 来查询广告系列的分析数据。这些 AWS CLI 示例是针对微软 Windows 进行格式化的。对于 Unix、Linux 和 macOS，请将插入符号 (^) 行继续符替换为反斜杠 (\$1)。 ------ #### [ REST API ] 要使用 Amazon Pinpoint REST API 查询活动的分析数据，请向[活动指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html) URI 发送 HTTP(S) GET 请求。在此 URI 中，为所需的路径参数指定适当的值： ``` https://endpoint/v1/apps/application-id/campaigns/campaign-id/kpis/daterange/kpi-name ``` 其中： + *endpoint*是托管与活动关联的项目的 AWS 区域的 Amazon Pinpoint 终端节点。 + *application-id* 是与活动关联的项目的唯一标识符。 + *campaign-id* 是活动的唯一标识符。 + *kpi-name*是要查询的指标的`kpi-name`值。 所有参数都应是 URL 编码的。 要应用一个筛选器来查询特定日期范围的数据，请将 `start-time` 和 `end-time` 查询参数和值附加到 URI。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。使用 & 符号分隔参数。 例如，以下请求会检索在 2019 年 7 月 19 日至 2019 年 7 月 26 日期间，对于某个活动的所有运行，消息送达的唯一端点的数量： ``` https://pinpoint.us-east-1.amazonaws.com/v1/apps/1234567890123456789012345example/campaigns/80b8efd84042ff8d9c96ce2f8example/kpis/daterange/unique-deliveries?start-time=2019-07-19T00:00:00Z&end-time=2019-07-26T23:59:59Z ``` 其中： + `pinpoint.us-east-1.amazonaws.com` 是托管项目的 AWS 区域的 Amazon Pinpoint 端点。 + `1234567890123456789012345example` 是与活动关联的项目的唯一标识符。 + `80b8efd84042ff8d9c96ce2f8example` 是活动的唯一标识符。 + `unique-deliveries` 是 *endpoint deliveries* 活动指标的 `kpi-name` 值，该指标用于报告对于某个活动的所有运行，消息送达到的唯一端点数量。 + `2019-07-19T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-07-26T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ #### [ AWS CLI ] 要使用查询广告系列的分析数据 AWS CLI，请使用**get-campaign-date-range-kpi**命令并为所需参数指定相应的值： ``` C:\> aws pinpoint get-campaign-date-range-kpi ^ --application-id application-id ^ --campaign-id campaign-id ^ --kpi-name kpi-name ``` 其中： + *application-id* 是与活动关联的项目的唯一标识符。 + *campaign-id* 是活动的唯一标识符。 + *kpi-name*是要查询的指标的`kpi-name`值。 要应用一个筛选器来查询特定日期范围的数据，请将 `start-time` 和 `end-time` 参数和值添加到您的查询。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。例如，以下请求会检索在 2019 年 7 月 19 日至 2019 年 7 月 26 日期间，对于某个活动的所有运行，消息送达的唯一端点的数量： ``` C:\> aws pinpoint get-campaign-date-range-kpi ^ --application-id 1234567890123456789012345example ^ --campaign-id 80b8efd84042ff8d9c96ce2f8example ^ --kpi-name unique-deliveries ^ --start-time 2019-07-19T00:00:00Z ^ --end-time 2019-07-26T23:59:59Z ``` 其中： + `1234567890123456789012345example` 是与活动关联的项目的唯一标识符。 + `80b8efd84042ff8d9c96ce2f8example` 是活动的唯一标识符。 + `unique-deliveries` 是 *endpoint deliveries* 活动指标的 `kpi-name` 值，该指标用于报告对于某个活动的所有运行，消息送达到的唯一端点数量。 + `2019-07-19T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-07-26T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ #### [ SDK for Java ] 要使用查询广告系列的分析数据 适用于 Java 的 AWS SDK，请使用[广告活动指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html) API **GetCampaignDateRangeKpiRequest** 的方法。为所需的参数指定相应的值： ``` GetCampaignDateRangeKpiRequest request = new GetCampaignDateRangeKpiRequest() .withApplicationId("applicationId") .withCampaignId("campaignId") .withKpiName("kpiName") ``` 其中： + *applicationId* 是与活动关联的项目的唯一标识符。 + *campaignId* 是活动的唯一标识符。 + *kpiName*是要查询的指标的`kpi-name`值。 要应用一个筛选器来查询特定日期范围的数据，请将 `startTime` 和 `endTime` 参数和值包含在您的查询中。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。例如，以下请求会检索在 2019 年 7 月 19 日至 2019 年 7 月 26 日期间，对于某个活动的所有运行，消息送达的唯一端点的数量： ``` GetCampaignDateRangeKpiRequest request = new GetCampaignDateRangeKpiRequest() .withApplicationId("1234567890123456789012345example") .withCampaignId("80b8efd84042ff8d9c96ce2f8example") .withKpiName("unique-deliveries") .withStartTime(Date.from(Instant.parse("2019-07-19T00:00:00Z"))) .withEndTime(Date.from(Instant.parse("2019-07-26T23:59:59Z"))); ``` 其中： + `1234567890123456789012345example` 是与活动关联的项目的唯一标识符。 + `80b8efd84042ff8d9c96ce2f8example` 是活动的唯一标识符。 + `unique-deliveries` 是 *endpoint deliveries* 活动指标的 `kpi-name` 值，该指标用于报告对于某个活动的所有运行，消息送达到的唯一端点数量。 + `2019-07-19T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-07-26T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ 发送查询后，Amazon Pinpoint 在 JSON 响应中返回查询结果。结果的结构因您查询的指标而异。一些指标仅返回一个值。例如，上述示例中使用的 *endpoint deliveries* (`unique-deliveries`) 活动指标只返回一个值，即，对于某个活动的所有运行，消息送达到的唯一端点数。在这种情况下，JSON 响应如下所示： ``` { "CampaignDateRangeKpiResponse":{ "ApplicationId":"1234567890123456789012345example", "CampaignId":"80b8efd84042ff8d9c96ce2f8example", "EndTime":"2019-07-26T23:59:59Z", "KpiName":"unique-deliveries", "KpiResult":{ "Rows":[ { "Values":[ { "Key":"UniqueDeliveries", "Type":"Double", "Value":"123.0" } ] } ] }, "StartTime":"2019-07-19T00:00:00Z" } } ``` 另一些指标返回多个值，并按相关字段对这些值进行分组。如果指标返回多个值，则 JSON 响应将包含一个字段，该字段指示对数据进行分组时所用的字段。 要了解有关查询结果结构的更多信息，请参阅[使用 JSON 查询结果](analytics-query-results.md)。 # 查询多个活动的 Amazon Pinpoint 数据 可通过两种方式查询多个活动的数据。哪种方式最佳，这取决于您是否要查询均与同一项目关联的活动的数据。如果您要查询，则最佳方式还取决于您是要查询所有这些活动的数据，还是仅查询一部分活动的数据。 要查询与不同项目关联的活动的数据，或仅查询与同一项目关联的部分活动的数据，最佳方式是创建并运行一系列单独的查询，并且一个查询对应一个活动。上一部分说明了如何仅查询一个活动的数据。 要查询与同一项目关联的所有活动的数据，可以使用[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API。为以下所需的参数指定值： + **application-id** – 项目 ID，它是项目的唯一标识符。在 Amazon Pinpoint 中，*项目* 和*应用程序* 具有相同的含义。 + **kpi-name** – 要查询的指标的名称。此值描述了关联的指标并包含两个或两个以上的术语，这些术语由小写字母数字字符组成并由连字符分隔。有关受支持的指标及其 `kpi-name` 值的完整列表，请参阅[项目、活动和旅程的标准指标](analytics-standard-metrics.md)。 您也可以按日期范围筛选数据。如果未指定日期范围，则 Amazon Pinpoint 返回前 31 个日历日期间的数据。要按不同的日期筛选数据，请使用支持的日期范围参数指定日期范围的起始和截止日期和时间。这些值应采用扩展的 ISO 8601 格式，并使用协调世界时 (UTC)，例如，`2019-07-19T20:00:00Z` 表示协调世界时 2019 年 7 月 19 日晚上 8 点。日期范围是包含性的，必须限制为不超过 31 个日历天。此外，起始日期和时间必须距离当前日期不到 90 天。 以下示例展示了如何使用 Amazon Pinpoint REST API AWS CLI、和，来查询广告活动的分析数据。 适用于 Java 的 AWS SDK您可以使用任何支持的 AWS SDK 来查询广告系列的分析数据。这些 AWS CLI 示例是针对微软 Windows 进行格式化的。对于 Unix、Linux 和 macOS，请将插入符号 (^) 行继续符替换为反斜杠 (\$1)。 ------ #### [ REST API ] 要使用 Amazon Pinpoint REST API 查询多个活动的分析数据，请向[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) URI 发送 HTTP(S) GET 请求。在此 URI 中，为所需的路径参数指定适当的值： ``` https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name ``` 其中： + *endpoint*是托管与活动关联的项目的 AWS 区域的 Amazon Pinpoint 终端节点。 + *application-id* 是与活动关联的项目的唯一标识符。 + *kpi-name*是要查询的指标的`kpi-name`值。 所有参数都应是 URL 编码的。 要应用一个筛选器来检索特定日期范围的数据，请将 `start-time` 和 `end-time` 查询参数和值附加到 URI。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。使用 & 符号分隔参数。 例如，以下请求会检索在 2019 年 7 月 19 日至 2019 年 7 月 26 日期间，对于某个项目的每个活动，消息送达到的唯一端点的数量： ``` https://pinpoint.us-east-1.amazonaws.com/v1/apps/1234567890123456789012345example/kpis/daterange/unique-deliveries-grouped-by-campaign?start-time=2019-07-19T00:00:00Z&end-time=2019-07-26T23:59:59Z ``` 其中： + `pinpoint.us-east-1.amazonaws.com` 是托管项目的 AWS 区域的 Amazon Pinpoint 端点。 + `1234567890123456789012345example` 是与活动关联的项目的唯一标识符。 + `unique-deliveries-grouped-by-campaign` 是 *endpoint deliveries, grouped by campaign* 应用程序指标的 `kpi-name` 值，该指标按照每个活动返回消息送达到的唯一端点的数量。 + `2019-07-19T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-07-26T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ #### [ AWS CLI ] 要使用查询多个广告系列的分析数据 AWS CLI，请使用**get-application-date-range-kpi**命令并为所需参数指定相应的值： ``` C:\> aws pinpoint get-application-date-range-kpi ^ --application-id application-id ^ --kpi-name kpi-name ``` 其中： + *application-id* 是与活动关联的项目的唯一标识符。 + *kpi-name*是要查询的指标的`kpi-name`值。 要应用一个筛选器来检索特定日期范围的数据，请将 `start-time` 和 `end-time` 参数和值包含在您的查询中。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。例如，以下请求会检索在 2019 年 7 月 19 日至 2019 年 7 月 26 日期间，对于某个项目的每个活动，消息送达到的唯一端点的数量： ``` C:\> aws pinpoint get-application-date-range-kpi ^ --application-id 1234567890123456789012345example ^ --kpi-name unique-deliveries-grouped-by-campaign ^ --start-time 2019-07-19T00:00:00Z ^ --end-time 2019-07-26T23:59:59Z ``` 其中： + `1234567890123456789012345example` 是与活动关联的项目的唯一标识符。 + `unique-deliveries-grouped-by-campaign` 是 *endpoint deliveries, grouped by campaign* 应用程序指标的 `kpi-name` 值，该指标按照每个活动返回消息送达到的唯一端点的数量。 + `2019-07-19T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-07-26T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ #### [ SDK for Java ] 要使用查询多个广告系列的分析数据 适用于 Java 的 AWS SDK，请使用[应用指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API **GetApplicationDateRangeKpiRequest** 的方法。为所需的参数指定相应的值： ``` GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest() .withApplicationId("applicationId") .withKpiName("kpiName") ``` 其中： + *applicationId* 是与活动关联的项目的唯一标识符。 + *kpiName*是要查询的指标的`kpi-name`值。 要应用一个筛选器来检索特定日期范围的数据，请将 `startTime` 和 `endTime` 参数和值包含在您的查询中。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。例如，以下请求会检索在 2019 年 7 月 19 日至 2019 年 7 月 26 日期间，对于某个项目的每个活动，消息送达到的唯一端点的数量： ``` GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest() .withApplicationId("1234567890123456789012345example") .withKpiName("unique-deliveries-grouped-by-campaign") .withStartTime(Date.from(Instant.parse("2019-07-19T00:00:00Z"))) .withEndTime(Date.from(Instant.parse("2019-07-26T23:59:59Z"))); ``` 其中： + `1234567890123456789012345example` 是与活动关联的项目的唯一标识符。 + `unique-deliveries-grouped-by-campaign` 是 *endpoint deliveries, grouped by campaign* 应用程序指标的 `kpi-name` 值，该指标按照每个活动返回消息送达到的唯一端点的数量。 + `2019-07-19T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-07-26T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ 发送查询后，Amazon Pinpoint 在 JSON 响应中返回查询结果。结果的结构因您查询的指标而异。一些指标仅返回一个值。另一些指标返回多个值，并按相关字段对这些值进行分组。如果指标返回多个值，则 JSON 响应将包含一个字段，该字段指示对数据进行分组时所用的字段。 例如，上述示例中使用的 *endpoint deliveries, grouped by campaign* (`unique-deliveries-grouped-by-campaign`) 应用程序指标返回多个值，即，对于某个项目的每个关联活动，消息送达到的唯一端点的数量。在这种情况下，JSON 响应如下所示： ``` { "ApplicationDateRangeKpiResponse":{ "ApplicationId":"1234567890123456789012345example", "EndTime":"2019-07-26T23: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-07-19T00:00:00Z" } } ``` 在此情况下，`GroupedBys` 字段指示按活动 ID 对值进行分组 (`CampaignId`)。 要了解有关查询结果结构的更多信息，请参阅[使用 JSON 查询结果](analytics-query-results.md)。 # 查询事务性消息的 Amazon Pinpoint 分析数据 除了使用 Amazon Pinpoint 控制台上的分析页面外，您还可以使用 Amazon Pinpoint APIs Analytics 查询分析数据，了解一部分标准指标，这些指标可以深入了解为项目发送的交易消息的交付和参与趋势。 其中的每个指标是一个可测量的值，也称为*关键绩效指标 (KPI)*，它们可以帮助您监控和评估事务性消息的绩效。例如，您可以使用指标来了解您发送了多少事务性电子邮件消息或短信，或者其中有多少消息送达收件人。Amazon Pinpoint 会自动收集和汇总您为项目发送的所有事务性电子邮件消息和短信的这类数据。它将数据存储 90 天。 如果您使用 Amazon Pinpoint Analytics APIs 来查询数据，则可以选择各种选项来定义查询的范围、数据、分组和筛选条件。为此，除了应用任何基于日期的筛选器之外，您还应使用参数来指定要查询的项目和指标。 本主题提供了有关如何选择这些选项和查询项目的事务性消息数据的示例，并对这些示例进行了说明。 ## 先决条件 在查询事务性消息的分析数据之前，收集以下信息很有用，可以用它们来定义查询： + **项目 ID** – 从中发送消息的项目的唯一标识符。在 Amazon Pinpoint API 中，此值存储在 `application-id` 属性中。在 Amazon Pinpoint 控制台上，此值在**所有项目**页面上显示为**项目 ID**。 + **日期范围**（可选）– 设置查询数据的日期范围的起始和截止日期和时间。日期范围是包含性的，必须限制为不超过 31 个日历天。此外，起始时间必须距离当前日期不到 90 天。如果未指定日期范围，Amazon Pinpoint 将自动查询前 31 个日历日期间的数据。 + **指标** – 要查询的指标的名称，更具体地说，即指标的 `kpi-name` 值。有关受支持的指标及其 `kpi-name` 值的完整列表，请参阅[项目、活动和旅程的标准指标](analytics-standard-metrics.md)。 它还可帮助确定是否要按相关字段对数据进行分组。如果您这样做，则可通过选择旨在自动为您对数据进行分组的指标来简化分析和报告。例如，Amazon Pinpoint 提供了多个标准指标来报告送达收件人的事务性短信的数量。其中的一个指标自动按日期对数据进行分组 (`txn-sms-delivered-grouped-by-date`)。另一个指标自动按国家或地区对数据进行分组 (`txn-sms-delivered-grouped-by-country`)。还有一个指标仅返回单个值—送达收件人的消息数 (`txn-sms-delivered`)。如果找不到能以您需要的方式来分组数据的标准指标，您可以开发一系列查询来返回您需要的数据。然后，您可以手动细分或者合并查询结果到您设计的自定义分组中。 最后，请务必确认您有权访问要查询的数据。有关更多信息，请参阅 [有关查询 Amazon Pinpoint 分析数据的 IAM 策略](analytics-permissions.md)。 # 查询事务性电子邮件消息的 Amazon Pinpoint 数据 要查询为项目发送的事务性电子邮件消息的数据，请使用[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API 并指定以下所需参数的值： + **application-id** – 项目 ID，它是项目的唯一标识符。在 Amazon Pinpoint 中，*项目* 和*应用程序* 具有相同的含义。 + **kpi-name** – 要查询的指标的名称。此值描述了关联的指标并包含两个或两个以上的术语，这些术语由小写字母数字字符组成并由连字符分隔。有关受支持的指标及其 `kpi-name` 值的完整列表，请参阅[项目、活动和旅程的标准指标](analytics-standard-metrics.md)。 您也可以应用筛选器来查询特定日期范围的数据。如果未指定日期范围，则 Amazon Pinpoint 返回前 31 个日历日期间的数据。要按不同的日期筛选数据，请使用支持的日期范围参数指定日期范围的起始和截止日期和时间。这些值应采用扩展的 ISO 8601 格式，并使用协调世界时 (UTC)，例如，`2019-09-06T20:00:00Z` 表示协调世界时 2019 年 9 月 6 日晚上 8 点。日期范围是包含性的，必须限制为不超过 31 个日历天。此外，起始日期和时间必须距离当前日期不到 90 天。 以下示例说明如何使用 Amazon Pinpoint REST API、和，查询交易电子邮件 AWS CLI的分析数据。 适用于 Java 的 AWS SDK您可以使用任何受支持的 AWS SDK 查询事务性消息的分析数据。这些 AWS CLI 示例是针对微软 Windows 进行格式化的。对于 Unix、Linux 和 macOS，请将插入符号 (^) 行继续符替换为反斜杠 (\$1)。 ------ #### [ REST API ] 要使用 Amazon Pinpoint REST API 查询事务性电子邮件消息的分析数据，请向[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) URI 发送 HTTP(S) GET 请求。在此 URI 中，为所需的路径参数指定适当的值： ``` https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name ``` 其中： + *endpoint*是托管该项目的 AWS 区域的 Amazon Pinpoint 终端节点。 + *application-id* 是项目的唯一标识符。 + *kpi-name*是要查询的指标的`kpi-name`值。 所有参数都应是 URL 编码的。 要应用一个筛选器来查询特定日期范围的数据，请将 `start-time` 和 `end-time` 查询参数和值附加到 URI。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。使用 & 符号分隔参数。 例如，以下请求会检索在 2019 年 9 月 6 日到 2019 年 9 月 13 日期间为项目发送的事务性电子邮件消息的数量： ``` https://pinpoint.us-east-1.amazonaws.com/v1/apps/1234567890123456789012345example/kpis/daterange/txn-emails-sent?start-time=2019-09-06T00:00:00Z&end-time=2019-09-13T23:59:59Z ``` 其中： + `pinpoint.us-east-1.amazonaws.com` 是托管项目的 AWS 区域的 Amazon Pinpoint 端点。 + `1234567890123456789012345example` 是项目的唯一标识符。 + `txn-emails-sent` 是*发送数*应用程序指标的 `kpi-name` 值，该指标用于报告为项目发送的事务性电子邮件消息的数量。 + `2019-09-06T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-09-13T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ #### [ AWS CLI ] 要使用查询交易电子邮件的分析数据 AWS CLI，请使用**get-application-date-range-kpi**命令并为所需参数指定相应的值： ``` C:\> aws pinpoint get-application-date-range-kpi ^ --application-id application-id ^ --kpi-name kpi-name ``` 其中： + *application-id* 是项目的唯一标识符。 + *kpi-name*是要查询的指标的`kpi-name`值。 要应用一个筛选器来查询特定日期范围的数据，请将 `start-time` 和 `end-time` 参数和值添加到您的查询。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。例如，以下请求会检索在 2019 年 9 月 6 日到 2019 年 9 月 13 日期间为项目发送的事务性电子邮件消息的数量： ``` C:\> aws pinpoint get-application-date-range-kpi ^ --application-id 1234567890123456789012345example ^ --kpi-name txn-emails-sent ^ --start-time 2019-09-06T00:00:00Z ^ --end-time 2019-09-13T23:59:59Z ``` 其中： + `1234567890123456789012345example` 是项目的唯一标识符。 + `txn-emails-sent` 是*发送数*应用程序指标的 `kpi-name` 值，该指标用于报告为项目发送的事务性电子邮件消息的数量。 + `2019-09-06T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-09-13T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ #### [ SDK for Java ] 要使用查询交易电子邮件的分析数据 适用于 Java 的 AWS SDK，请使用[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API **GetApplicationDateRangeKpiRequest** 的方法。为所需的参数指定相应的值： ``` GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest() .withApplicationId("applicationId") .withKpiName("kpiName") ``` 其中： + *applicationId* 是项目的唯一标识符。 + *kpiName*是要查询的指标的`kpi-name`值。 要应用一个筛选器来查询特定日期范围的数据，请将 `startTime` 和 `endTime` 参数和值包含在您的查询中。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。例如，以下请求会检索在 2019 年 9 月 6 日到 2019 年 9 月 13 日期间为项目发送的事务性电子邮件消息的数量： ``` GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest() .withApplicationId("1234567890123456789012345example") .withKpiName("txn-emails-sent") .withStartTime(Date.from(Instant.parse("2019-09-06T00:00:00Z"))) .withEndTime(Date.from(Instant.parse("2019-09-13T23:59:59Z"))); ``` 其中： + `1234567890123456789012345example` 是项目的唯一标识符。 + `txn-emails-sent` 是*发送数*应用程序指标的 `kpi-name` 值，该指标用于报告为项目发送的事务性电子邮件消息的数量。 + `2019-09-06T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-09-13T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ 发送查询后，Amazon Pinpoint 在 JSON 响应中返回查询结果。结果的结构因您查询的指标而异。一些指标仅返回一个值。例如，上述示例中使用的*发送数* (`txn-emails-sent`) 应用程序指标返回一个值，即从项目发送的事务性电子邮件消息的数量。在这种情况下，JSON 响应如下所示： ``` { "ApplicationDateRangeKpiResponse":{ "ApplicationId":"1234567890123456789012345example", "EndTime":"2019-09-13T23:59:59Z", "KpiName":"txn-emails-sent", "KpiResult":{ "Rows":[ { "Values":[ { "Key":"TxnEmailsSent", "Type":"Double", "Value":"62.0" } ] } ] }, "StartTime":"2019-09-06T00:00:00Z" } } ``` 另一些指标返回多个值，并按相关字段对这些值进行分组。如果指标返回多个值，则 JSON 响应将包含一个字段，该字段指示对数据进行分组时所用的字段。 要了解有关查询结果结构的更多信息，请参阅[使用 JSON 查询结果](analytics-query-results.md)。 # 查询事务性短信的 Amazon Pinpoint 数据 要查询已为项目发送的事务性短信的数据，请使用[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API 并指定以下所需参数的值： + **application-id** – 项目 ID，它是项目的唯一标识符。在 Amazon Pinpoint 中，*项目* 和*应用程序* 具有相同的含义。 + **kpi-name** – 要查询的指标的名称。此值描述了关联的指标并包含两个或两个以上的术语，这些术语由小写字母数字字符组成并由连字符分隔。有关受支持的指标及其 `kpi-name` 值的完整列表，请参阅[项目、活动和旅程的标准指标](analytics-standard-metrics.md)。 您也可以应用筛选器来查询特定日期范围的数据。如果未指定日期范围，则 Amazon Pinpoint 返回前 31 个日历日期间的数据。要按不同的日期筛选数据，请使用支持的日期范围参数以指定日期范围的起始和截止日期和时间。这些值应采用扩展的 ISO 8601 格式，并使用协调世界时 (UTC)，例如，`2019-09-06T20:00:00Z` 表示协调世界时 2019 年 9 月 6 日晚上 8 点。日期范围是包含性的，必须限制为不超过 31 个日历天。此外，起始日期和时间必须距离当前日期不到 90 天。 以下示例说明如何使用 Amazon Pinpoint REST API、和，查询交易短信 AWS CLI的分析数据。 适用于 Java 的 AWS SDK您可以使用任何支持的 AWS SDK 来查询交易消息的分析数据。这些 AWS CLI 示例是针对微软 Windows 进行格式化的。对于 Unix、Linux 和 macOS，请将插入符号 (^) 行继续符替换为反斜杠 (\$1)。 ------ #### [ REST API ] 要使用 Amazon Pinpoint REST API 查询事务性短信的分析数据，请向[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) URI 发送 HTTP(S) GET 请求。在此 URI 中，为所需的路径参数指定适当的值： ``` https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name ``` 其中： + *endpoint*是托管该项目的 AWS 区域的 Amazon Pinpoint 终端节点。 + *application-id* 是项目的唯一标识符。 + *kpi-name*是要查询的指标的`kpi-name`值。 所有参数都应是 URL 编码的。 要应用一个筛选器来检索特定日期范围的数据，请将 `start-time` 和 `end-time` 查询参数和值附加到 URI。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。使用 & 符号分隔参数。 例如，以下请求会检索在 2019 年 9 月 6 日到 2019 年 9 月 8 日期间的每一天发送的事务性短信的数量： ``` https://pinpoint.us-east-1.amazonaws.com/v1/apps/1234567890123456789012345example/kpis/daterange/txn-sms-sent-grouped-by-date?start-time=2019-09-06T00:00:00Z&end-time=2019-09-08T23:59:59Z ``` 其中： + `pinpoint.us-east-1.amazonaws.com` 是托管项目的 AWS 区域的 Amazon Pinpoint 端点。 + `1234567890123456789012345example` 是项目的唯一标识符。 + `txn-sms-sent-grouped-by-date` 是*按日期分组的发送数* 应用程序指标的 `kpi-name` 值，该指标返回日期范围内每天发送的事务性短信的数量。 + `2019-09-06T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-09-08T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ #### [ AWS CLI ] 要使用查询交易 SMS 消息的分析数据 AWS CLI，请使用**get-application-date-range-kpi**命令并为所需参数指定相应的值： ``` C:\> aws pinpoint get-application-date-range-kpi ^ --application-id application-id ^ --kpi-name kpi-name ``` 其中： + *application-id* 是项目的唯一标识符。 + *kpi-name*是要查询的指标的`kpi-name`值。 要应用一个筛选器来检索特定日期范围的数据，请将 `start-time` 和 `end-time` 参数和值包含在您的查询中。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。例如，以下请求会检索在 2019 年 9 月 6 日到 2019 年 9 月 8 日期间的每一天发送的事务性短信的数量： ``` C:\> aws pinpoint get-application-date-range-kpi ^ --application-id 1234567890123456789012345example ^ --kpi-name txn-sms-sent-grouped-by-date ^ --start-time 2019-09-06T00:00:00Z ^ --end-time 2019-09-08T23:59:59Z ``` 其中： + `1234567890123456789012345example` 是项目的唯一标识符。 + `txn-sms-sent-grouped-by-date` 是*按日期分组的发送数* 应用程序指标的 `kpi-name` 值，该指标返回日期范围内每天发送的事务性短信的数量。 + `2019-09-06T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-09-08T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ #### [ SDK for Java ] 要使用查询交易 SMS 消息的分析数据 适用于 Java 的 AWS SDK，请使用[应用程序指标](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) API **GetApplicationDateRangeKpiRequest** 的方法，并为所需参数指定相应的值： ``` GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest() .withApplicationId("applicationId") .withKpiName("kpiName") ``` 其中： + *applicationId* 是项目的唯一标识符。 + *kpiName*是要查询的指标的`kpi-name`值。 要应用一个筛选器来检索特定日期范围的数据，请将 `startTime` 和 `endTime` 参数和值包含在您的查询中。通过使用这些参数，您可采用扩展的 ISO 8601 格式，指定检索数据的包含性日期范围的起始和截止日期和时间。例如，以下请求会检索在 2019 年 9 月 6 日到 2019 年 9 月 8 日期间的每一天发送的事务性短信的数量： ``` GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest() .withApplicationId("1234567890123456789012345example") .withKpiName("txn-sms-sent-grouped-by-date") .withStartTime(Date.from(Instant.parse("2019-09-06T00:00:00Z"))) .withEndTime(Date.from(Instant.parse("2019-09-08T23:59:59Z"))); ``` 其中： + `1234567890123456789012345example` 是项目的唯一标识符。 + `txn-sms-sent-grouped-by-date` 是*按日期分组的发送数* 应用程序指标的 `kpi-name` 值，该指标返回日期范围内每天发送的事务性短信的数量。 + `2019-09-06T00:00:00Z` 是数据检索范围的第一个日期和时间（包含在检索日期范围内）。 + `2019-09-08T23:59:59Z` 是检索数据的截止日期和时间，也是包含性日期范围的一部分。 ------ 发送查询后，Amazon Pinpoint 在 JSON 响应中返回查询结果。结果的结构因您查询的指标而异。一些指标仅返回一个值。另一些指标返回多个值，并按相关字段对这些值进行分组。如果指标返回多个值，则 JSON 响应将包含一个字段，该字段指示对数据进行分组时所用的字段。 例如，上述示例中使用的*按日期分组的发送数* (`txn-sms-sent-grouped-by-date`) 应用程序指标将返回多个值，即指定日期范围内的每一天发送的事务性短信的数量。在这种情况下，JSON 响应如下所示： ``` { "ApplicationDateRangeKpiResponse":{ "ApplicationId":"1234567890123456789012345example", "EndTime":"2019-09-08T23:59:59Z", "KpiName":"txn-sms-sent-grouped-by-date", "KpiResult":{ "Rows":[ { "GroupedBys":[ { "Key":"Date", "Type":"String", "Value":"2019-09-06" } ], "Values":[ { "Key":"TxnSmsSent", "Type":"Double", "Value":"29.0" } ] }, { "GroupedBys":[ { "Key":"Date", "Type":"String", "Value":"2019-09-07" } ], "Values":[ { "Key":"TxnSmsSent", "Type":"Double", "Value":"35.0" } ] }, { "GroupedBys":[ { "Key":"Date", "Type":"String", "Value":"2019-09-08" } ], "Values":[ { "Key":"TxnSmsSent", "Type":"Double", "Value":"10.0" } ] } ] }, "StartTime":"2019-09-06T00:00:00Z" } } ``` 在此情况下，`GroupedBys` 字段指示按日历日对值进行分组 (`Date`)。这意味着： + 在 2019 年 9 月 6 日发送了 29 条消息。 + 在 2019 年 9 月 7 日发送了 35 条消息。 + 在 2019 年 9 月 8 日发送了 10 条消息。 要了解有关查询结果结构的更多信息，请参阅[使用 JSON 查询结果](analytics-query-results.md)。 # 使用 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)。