**支援終止通知：**2026 年 10 月 30 日， AWS 將結束對 Amazon Pinpoint 的支援。2026 年 10 月 30 日之後，您將無法再存取 Amazon Pinpoint 主控台或 Amazon Pinpoint 資源 (端點、區段、行銷活動、旅程和分析)。如需詳細資訊，請參閱 [Amazon Pinpoint 終止支援](https://docs.aws.amazon.com/console/pinpoint/migration-guide)。**注意：**與 SMS、語音、行動推播、OTP 和電話號碼驗證相關的 APIs 不受此變更影響，並受 AWS 最終使用者傳訊支援。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 查詢 Amazon Pinpoint 分析資料
除了使用 Amazon Pinpoint 主控台的分析頁面，也可以使用 Amazon Pinpoint Analytics API 查詢標準指標子集的分析資料，深入了解與使用者互動、行銷活動推廣等相關的趨勢。這些指標也稱為「關鍵績效指標 (KPI)」**，是可測量的值，可協助您監控與評估專案、行銷活動和行程的績效。
若使用 API 查詢分析資料，可以使用自選的報告工具分析資料，不須登入 Amazon Pinpoint 主控台或分析 Amazon Kinesis 串流等來源的原始事件資料。例如，您可以建置自訂儀表板，顯示每週的行銷活動結果，或是提供您行銷活動交付率的深入分析。
您可以使用 Amazon Pinpoint REST API、 AWS Command Line Interface (AWS CLI) 或 SDK 來 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 年 7 月 19 日 8:00 PM UTC 即以 `2019-07-19T20:00:00Z` 顯示。
日期範圍包含在內，且必須不超過 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 可以查詢標準指標子集的分析資料，亦稱為*關鍵績效指標 (KPI)*，適用於 Amazon Pinpoint 專案、行銷活動和旅程。這些指標可協助您監控與評估專案、行銷活動和行程的績效。
若要管理對此資料的存取，您可以建立 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"
]
}
]
}
```
------
其中 *accountId* 是 AWS 您的帳戶 ID。
但是，根據最佳實務，您應該定義遵循「最低權限」**原則的政策。換句話說，您應建立其中只包含執行特定任務所需許可的政策。若要支援此實務並實作更精細的控制，您可以限制對特定 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 帳戶 ID。
+ *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 專案、行銷活動和旅程的標準指標
您可以使用 Amazon Pinpoint Analytics API 查詢分析資料，以取得適用於 Amazon Pinpoint 專案、行銷活動和旅程的標準指標子集。這些指標也稱為「關鍵績效指標 (KPI)」**，是可測量的值，可協助您監控與評估專案、行銷活動和行程的績效。
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 | Description |
| --- | --- | --- |
| 交付率 | `successful-delivery-rate` | 對於與專案相關聯的所有行銷活動，交付給收件人的訊息百分比。 此指標的計算方式為專案的所有行銷活動傳送並交付給收件人的訊息數量，除以所有行銷活動傳送的訊息數量。 |
| Delivery rate, grouped by date (交付率，依日期分組) | `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-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 | Description |
| --- | --- | --- |
| 點按數 | `txn-emails-clicked` | 收件人點按訊息中連結的次數。如果單一收件人點按訊息中的多個連結，或點按相同連結多次，則會在計數中包含每個點按。 |
| Clicks, grouped by date (點按數，依日期分組) | `txn-emails-clicked-grouped-by-date` | 收件人於指定日期範圍內每天點選訊息中連結的次數。如果單一收件人點按訊息中的多個連結，或點按相同連結多次，則會在計數中包含每個點按。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| 投訴率 | `txn-emails-complaint-rate` | 收件人回報為未經要求或不想收到的電子郵件的訊息百分比。 此指標的計算方式為：收件人回報為未經要求或不想收到的電子郵件的訊息數量，除以傳送的訊息數量。 |
| Complaint rate, grouped by date (投訴率，依日期分組) | `txn-emails-complaint-rate-grouped-by-date` | 在指定日期範圍內的每一天，收件人回報為未經要求或不想收到的電子郵件的訊息百分比。 此指標的計算方式為：在指定日期範圍內的每一天，收件人回報為未經要求或不想收到的電子郵件的訊息數量，除以傳送的訊息數量。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| 投訴 | `txn-emails-with-complaints` | 收件人回報為未經要求或不想收到的電子郵件的訊息數量。 |
| Complaints, grouped by date (投訴數，依日期分組) | `txn-emails-with-complaints-grouped-by-date` | 在指定日期範圍內的每一天，收件人回報為未經要求或不想收到的電子郵件的訊息數量。此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| 交付 | `txn-emails-delivered` | 交付給收件人的訊息數量 此指標的計算方式為：傳送的訊息數量，減去由於軟退信或硬退信或因拒絕而無法交付的訊息數量。如果 Amazon Pinpoint 判定訊息含惡意程式碼，將拒絕訊息。Amazon Pinpoint 不會嘗試傳送被拒絕的訊息。 |
| Deliveries, grouped by date (交付數，依日期分組) | `txn-emails-delivered-grouped-by-date` | 在指定日期範圍內每天交付給收件人的訊息數量。 此指標的計算方式為：在指定日期範圍內的每一天，傳送的訊息數量，減去由於軟退信或硬退信或因拒絕而無法交付的訊息數量。如果 Amazon Pinpoint 判定訊息含惡意程式碼，將拒絕訊息。Amazon Pinpoint 不會嘗試傳送被拒絕的訊息。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| 交付率 | `txn-emails-delivery-rate` | 交付給收件人的訊息百分比。 此指標的計算方式為：傳送並交付給收件人的訊息數量，除以傳送的訊息數量。 |
| Delivery rate, grouped by date (交付率，依日期分組) | `txn-emails-delivery-rate-grouped-by-date` | 在指定日期範圍內每天交付給收件人的訊息百分比。 此指標的計算方式為：在指定日期範圍內的每一天，傳送並交付給收件人的訊息數量，除以傳送的訊息數量。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| 硬退信 | `txn-emails-hard-bounced` | 由於硬退信而無法交付給收件人的訊息數量。如果存在永久性問題導致訊息無法交付 (例如收件人的電子郵件地址不存在)，將會硬退信。 |
| Hard bounces, grouped by date (硬退信，依日期分組) | `txn-emails-hard-bounced-grouped-by-date` | 在指定日期範圍內的每一天，由於硬退信而無法交付給收件人的訊息數量。如果存在永久性問題導致訊息無法交付 (例如收件人的電子郵件地址不存在)，將會硬退信。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| 開啟數 | `txn-emails-opened` | 收件人開啟的訊息數量。 |
| Opens, grouped by date (開啟數，依日期分組) | `txn-emails-opened-grouped-by-date` | 收件人於指定日期範圍內每天開啟的訊息數量。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| 傳送 | `txn-emails-sent` | 傳送的訊息數量。 |
| Sends, grouped by date (傳送數，依日期分組) | `txn-emails-sent-grouped-by-date` | 在指定日期範圍內每天傳送的訊息數量。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| Soft bounces (軟退信) | `txn-emails-soft-bounced` | 由於軟退信而無法交付給收件人的訊息數量。如果存在暫時性問題導致訊息無法交付 (例如收件人的收件匣已滿，或接收伺服器暫時無法使用)，則會軟退信。 |
| Soft bounces, grouped by date (軟退信，依日期分組) | `txn-emails-soft-bounced-grouped-by-date` | 在指定日期範圍內的每一天，由於軟退信而無法交付給收件人的訊息數量。如果存在暫時性問題導致訊息無法交付 (例如收件人的收件匣已滿，或接收伺服器暫時無法使用)，則會軟退信。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| Unique user click events (唯一使用者點按事件數) | `txn-emails-unique-clicks` | 點按訊息中連結的唯一收件人 (端點) 數量。 與 **Clicks (點按數)** 指標不同，此指標回報的是點選連結的唯一收件人數量，而非發生的點按事件數量。例如，如果單一收件人點按相同訊息中的多個連結，或多次點按相同的連結，則此指標只會針對該收件人回報一個點按事件。 |
| Unique user click events, grouped by date (唯一使用者點按事件數，依日期分組) | `txn-emails-unique-clicks-grouped-by-date` | 在指定日期範圍內每天點按訊息中連結的唯一收件人 (端點) 數量。 與 **Clicks, grouped by date (點按數，依日期分組)** 不同，此指標回報的是點按連結的唯一收件人數量，而非發生的點按事件數量。例如，如果單一收件人點按相同訊息中的多個連結，或多次點按相同的連結，則此指標只會針對該收件人回報一個點按事件。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| Unique user open events (唯一使用者開啟事件數) | `txn-emails-unique-opens` | 開啟訊息的唯一收件人 (端點) 數量。 與 **Opens (開啟數)** 指標不同，此指標回報的是開啟訊息的唯一收件人數量，而非發生的開啟事件數量。例如，如果單一收件人多次開啟相同訊息，則此指標只會針對該收件人回報一個開啟事件。 |
| Unique user open events, grouped by date (唯一使用者開啟事件數，依日期分組) | `txn-emails-unique-opens-grouped-by-date` | 在指定日期範圍內每天開啟訊息的唯一收件人 (端點) 數量。 與 **Opens, grouped by date (開啟數，依日期分組)** 指標不同，此指標回報的是開啟訊息的唯一收件人數量。而非發生的開啟事件數量。例如，如果單一收件人多次開啟相同訊息，則此指標只會針對該收件人回報一個開啟事件。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
# 交易簡訊的 Amazon Pinpoint 應用程式指標
下表列出並描述了標準應用程式指標，您可以針對與 Amazon Pinpoint 專案相關聯的所有交易 SMS 訊息，查詢這些指標並監控趨勢。若要查詢這些指標的資料，請使用 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 | Description |
| --- | --- | --- |
| 每則訊息的平均價格 (依國家/地區分組) | `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` | 傳訊到各國家/地區或區域的單則訊息部分平均成本。訊息部分是 SMS 訊息的一部分。價格以美分的千分之幾顯示。假設此屬性的值是 645，則我們收取的傳訊費用是 0.645¢ (645/1000 = 0.645¢ = \$10.00645)。 此指標的計算方法是，傳訊給各國家/地區或區域的收件人所產生的所有訊息部分總成本，除以傳送的訊息部分數。 此指標的查詢結果會依國家或區域分組，採用 ISO 3166-1 alpha-2 格式。 |
| 交付 | `txn-sms-delivered` | 交付給收件人的訊息數量 |
| Deliveries, grouped by country (交付數，依國家或區域分組) | `txn-sms-delivered-grouped-by-country` | 針對訊息所傳送至的國家或區域，交付給收件人的訊息數量。 此指標的查詢結果會依國家或區域分組，採用 ISO 3166-1 alpha-2 格式。 |
| Deliveries, grouped by date (交付數，依日期分組) | `txn-sms-delivered-grouped-by-date` | 在指定日期範圍內每天交付給收件人的訊息數量。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| Delivery errors (交付錯誤數) | `txn-sms-error-distribution` | 針對發生的每種錯誤類型，嘗試交付訊息時發生錯誤的次數。 針對發生的每種錯誤類型，此指標的查詢結果會依錯誤碼分組。 |
| 交付率 | `txn-sms-delivery-rate` | 交付給收件人的訊息百分比。 此指標的計算方式為：傳送並交付給收件人的訊息數量，除以傳送的訊息數量。 |
| Delivery rate, grouped by date (交付率，依日期分組) | `txn-sms-delivery-rate-grouped-by-date` | 在指定日期範圍內每天交付給收件人的訊息百分比。 此指標的計算方式為：在指定日期範圍內的每一天，傳送並交付給收件人的訊息數量，除以傳送的訊息數量。 此指標的查詢結果會依日曆天分組，採用延伸 ISO 8601 格式。 |
| 已交付的訊息部分 | `txn-sms-delivered-by-parts` | 已交付的訊息部分數。*訊息部分*是 SMS 訊息的一部分。如果 SMS 訊息包含的字元數超過 SMS 通訊協定允許的字元數，Amazon Pinpoint 會視需要將訊息分割成多則訊息，以將訊息傳送給收件人。 |
| 已交付的訊息部分，依國家/地區分組 | `txn-sms-delivered-by-parts-grouped-by-country` | 已交付給各國家/地區或區域的訊息部分數。*訊息部分*是 SMS 訊息的一部分。 此指標的查詢結果會依國家或區域分組，採用 ISO 3166-1 alpha-2 格式。 |
| 已傳送的訊息部分 | `txn-sms-sent-by-parts` | 已傳送的訊息部分的數目。*訊息部分*是 SMS 訊息的一部分。如果 SMS 訊息包含的字元數超過 SMS 通訊協定允許的字元數，Amazon Pinpoint 會視需要將訊息分割成多則訊息，以將訊息傳送給收件人。 |
| 已傳送的訊息部分，依國家/地區分組 | `txn-sms-sent-by-parts-grouped-by-country` | 已傳送到各國家/地區或區域的訊息部分數。*訊息部分*是 SMS 訊息的一部分。 此指標的查詢結果會依國家或區域分組，採用 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 格式。 |
| Total price, grouped by country (總價，依國家或區域分組) | `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 | Description |
| --- | --- | --- |
| 退信率 | `hard-bounce-rate` | 對於所有行銷活動執行，無法交付其收件人的電子郵件訊息百分比。此指標只測量硬退信，也就是收件人的電子郵件地址存在永久性問題，導致無法交付訊息的情況。 此指標的計算方式為專案的所有行銷活動執行傳送的退信的電子郵件訊息數量，除以所有行銷活動執行傳送的電子郵件訊息數量。 |
| 退信率，依行銷活動執行分組 | `hard-bounce-rate-grouped-by-campaign-activity` | 對於每個行銷活動執行，無法交付給收件人的電子郵件訊息百分比。此指標只測量硬退信，也就是收件人的電子郵件地址存在永久性問題，導致無法交付訊息的情況。 此指標的計算方式為專案的行銷活動執行傳送的退信的電子郵件訊息數量，除以行銷活動執行傳送的電子郵件訊息數量。 此指標的查詢結果會依行銷活動的活動 ID (`CampaignActivityId`) 分組，這是可唯一識別行銷活動執行的字串。 |
| 交付率 | `successful-delivery-rate` | 對於所有行銷活動執行，交付給收件人的訊息百分比。 此指標的計算方式為所有行銷活動執行傳送並交付給收件人的訊息數量，除以所有行銷活動執行傳送的訊息數量。 |
| 交付率，依行銷活動執行分組 | `successful-delivery-rate-grouped-by-campaign-activity` | 對於每個行銷活動執行，交付給收件人的訊息百分比。 此指標的計算方式為行銷活動執行傳送並交付給收件人的訊息數量，除以行銷活動執行傳送的訊息數量。 此指標的查詢結果會依行銷活動的活動 ID (`CampaignActivityId`) 分組，這是可唯一識別行銷活動執行的字串。 |
| Delivery rate, grouped by date (交付率，依日期分組) | `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-grouped-by-campaign-activity` | 對於每個行銷活動執行，由收件人開啟的推送通知百分比。 此指標的計算方式為：由行銷活動回合傳送並經收件人開啟的推送通知數量，除以行銷活動回合傳送並交付予收件人的推送通知數量。 此指標的查詢結果會依行銷活動的活動 ID (`CampaignActivityId`) 分組，這是可唯一識別行銷活動執行的字串。 |
| 開啟的推送總數，依行銷活動執行分組 | `direct-push-opens-grouped-by-campaign-activity` | 對於每個行銷活動執行，由收件人開啟的推送通知數量。 此指標的查詢結果會依行銷活動的活動 ID (`CampaignActivityId`) 分組，這是可唯一識別行銷活動執行的字串。 |
| Total SMS spend (簡訊費用總計) | sms-spend | 所有行銷活動傳送 SMS 所支出的總金額 (以 milicents 為單位)。 |
# 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 | Description |
| --- | --- | --- |
| 點按數 | `journey-emails-clicked` | 收件人點按訊息中連結的次數。如果單一收件人點按訊息中的多個連結，或多次點按相同連結，每次點按都會計入計數。 |
| 按一下，依活動分組 | `emails-clicked-grouped-by-journey-activity` | 行程中每項活動之參與者按下郵件中連結的次數。如果單一收件人點按訊息中的多個連結，或多次點按相同連結，每次點按都會計入計數。 此指標的查詢結果會依活動 ID (`JourneyActivityId`) 分組，這是唯一能夠識別活動的字串。 |
| 投訴 | `journey-emails-complained` | 參與者回報為未經要求或不想收到的電子郵件訊息數量。 |
| 投訴，依活動分組 | `emails-complained-grouped-by-journey-activity` | 行程中每項活動之參與者回報為未經要求或不想收到的電子郵件訊息數量。此指標的查詢結果會依活動 ID (`JourneyActivityId`) 分組，這是唯一能夠識別活動的字串。 |
| 交付 | `journey-emails-delivered` | 已交付予參與者的訊息數量。 此指標的計算方式為：傳送的訊息數量，減去由於軟退信或硬退信或因拒絕而無法交付的訊息數量。 |
| 交付數，依活動分組 | `emails-delivered-grouped-by-journey-activity` | 行程中每項活動之已交付予參與者的郵件數目。 此指標的計算方式為：行程中每項活動已傳送的訊息數量，減去由於軟退信或硬退信或因拒絕而無法交付的訊息數量。 此指標的查詢結果會依活動 ID (`JourneyActivityId`) 分組，這是唯一能夠識別活動的字串。 |
| 硬退信 | `journey-emails-hardbounced` | 由於硬退信而無法交付予參與者的訊息數量。如果存在永久性問題導致訊息無法交付 (例如參與者的電子郵件地址不存在)，將會硬退信。 |
| 硬退信，依活動分組 | `emails-hardbounced-grouped-by-journey-activity` | 行程中每項活動之因為硬退信而無法交付予參與者的郵件數量。如果存在永久性問題導致訊息無法交付 (例如參與者的電子郵件地址不存在)，將會硬退信。 此指標的查詢結果會依活動 ID (`JourneyActivityId`) 分組，這是唯一能夠識別活動的字串。 |
| 開啟數 | `journey-emails-opened` | 參與者開啟的訊息數量。 |
| 開啟，依活動分組 | `emails-opened-grouped-by-journey-activity` | 行程中每項活動之參與者開啟的郵件數量。 此指標的查詢結果會依活動 ID (`JourneyActivityId`) 分組，這是唯一能夠識別活動的字串。 |
| 拒絕 | `journey-emails-rejected` | 因為被拒絕而未傳送給參與者的郵件數目。如果 Amazon Pinpoint 判定訊息含惡意程式碼，將拒絕訊息。Amazon Pinpoint 不會嘗試傳送被拒絕的訊息。 |
| 拒絕，依活動分組 | `emails-rejected-grouped-by-journey-activity` | 行程中每項活動之因被拒絕而未傳送給參與者的郵件數目。如果 Amazon Pinpoint 判定訊息含惡意程式碼，將拒絕訊息。Amazon Pinpoint 不會嘗試傳送被拒絕的訊息。 此指標的查詢結果會依活動 ID (`JourneyActivityId`) 分組，這是唯一能夠識別活動的字串。 |
| 傳送 | `journey-emails-sent` | 傳送的訊息數量。 |
| 傳送，依活動分組 | `emails-sent-grouped-by-journey-activity` | 行程中每項活動之已傳送的郵件數目。 此指標的查詢結果會依活動 ID (`JourneyActivityId`) 分組，這是唯一能夠識別活動的字串。 |
| Soft bounces (軟退信) | `journey-emails-softbounced` | 由於軟退信而無法交付了參與者的訊息數量。如果存在暫時性問題導致訊息無法交付 (例如參與者的收件匣已滿，或接收伺服器暫時無法使用)，則會軟退信。 |
| 軟退信，依活動分組 | `emails-softbounced-grouped-by-journey-activity` | 行程中每項活動之因為軟退信而無法交付予參與者的郵件數量。如果存在暫時性問題導致訊息無法交付 (例如參與者的收件匣已滿，或接收伺服器暫時無法使用)，則會軟退信。 此指標的查詢結果會依活動 ID (`JourneyActivityId`) 分組，這是唯一能夠識別活動的字串。 |
| 取消訂閱 | `journey-emails-unsubscribed` | 參與者按下郵件中取消訂閱連結的次數。如果單一參與者多次按下同一個取消訂閱連結，則每次按下都會計入計數。 |
| 取消訂閱，依活動分組 | `emails-unsubscribed-grouped-by-journey-activity` | 行程中每項活動之參與者按下郵件中取消訂閱連結的次數。如果單一參與者多次按下同一個取消訂閱連結，則每次按下都會計入計數。 此指標的查詢結果會依活動 ID (`JourneyActivityId`) 分組，這是唯一能夠識別活動的字串。 |
# Amazon Pinpoint 旅程執行指標
下表列出並描述了標準執行指標，您可以查詢這些指標，以評估 Amazon Pinpoint 旅程中參與者的狀態。若要查詢這些指標的資料，請使用 Amazon Pinpoint API 的[旅程執行指標](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-journeys-journey-id-execution-metrics.html)資源。表格中的 **Field (欄位)** 欄位可識別查詢結果所顯示之每項指標的欄位名稱。
| 指標 | 欄位 | Description |
| --- | --- | --- |
| 活動參與者 | `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)資源。表格中的 **Metrics (指標)** 欄位會列出查詢結果所顯示之各活動類型的欄位。並提供每個欄位的簡短描述。
| 活動類型 | 指標 |
| --- | --- |
| 是/否分割 (`CONDITIONAL_SPLIT`) | 這些指標為： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/developerguide/journey-metrics-activity-execution.html) 活動中每個路徑可使用的其他指標。如需這些指標的相關資訊，請參閱本表中該活動類型的資料列。 |
| 暫停 (`HOLDOUT`) | 這些指標為： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/pinpoint/latest/developerguide/journey-metrics-activity-execution.html) |
| 電子郵件 (`MESSAGE`) | 這些指標為： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/pinpoint/latest/developerguide/journey-metrics-activity-execution.html) |
| 聯絡中心 (`CONTACT_CENTER`) | 這些指標為： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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)資源。下表列出各類活動查詢結果中顯示的欄位。
****
| 指標名稱 | 適用於旅程、行銷活動或兩者 | Description |
| --- | --- | --- |
| 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 | 旅程 | 已從執行移除，因為旅程已暫停。 |
| ENDED | 旅程 | 已從執行移除，因為旅程已結束。 |
| TREATMENT\$1HOLDOUT | 行銷活動 | 這是在 A/B 活動中，針對隊列與目前處理方法不符的端點而發出。例如在 50/50 A/B 拆分測試中，50% 的端點將針對各種處理方法發出此指標 |
| ENDPOINT\$1ESTIMATED\$1TIMEZONE | 旅程 | 時區判斷能夠判斷出端點的時區。 |
# 查詢行銷活動的 Amazon Pinpoint 分析資料
除了使用 Amazon Pinpoint 主控台的分析頁面外，也可以使用 Amazon Pinpoint Analytics API 查詢標準指標子集的分析資料，深入了解行銷活動的成果和互動趨勢。
這些指標每一個都是可測量的值，也稱為「關鍵績效指標 (KPI)」**，可協助您監控與評估一或多個行銷活動的績效。例如，您可以使用指標了解行銷活動訊息送往的端點數量，或是這些訊息交付給預期端點的數量。
Amazon Pinpoint 會自動收集並彙總所有行銷活動的資料。資料可存放 90 天。如果您使用 Mobile AWS SDK 將行動應用程式與 Amazon Pinpoint 整合，Amazon Pinpoint 會將此支援擴展為包含其他指標，例如收件人開啟的推送通知百分比。如需整合行動裝置應用程式的資訊，請參閱 [將 Amazon Pinpoint 與您的應用程式整合](integrate.md)。
若使用 Amazon Pinpoint Analytics API 查詢資料，可以選擇定義查詢範圍、資料、群組和篩選條件的各種選項。您可以使用參數來執行此作業；這些參數會指定您希望查詢的專案、行銷活動和指標，以及任何您希望套用的日期類型篩選條件。
本主題會提供範例，說明如何選擇這些選項，以及如何查詢一或多個行銷活動的資料。
## 先決條件
在您查詢一或多個行銷活動的分析資料前，收集以下用於定義查詢的資訊，對您將會有所助益：
+ **專案 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 年 7 月 19 日 8:00 PM UTC 即以 `2019-07-19T20:00:00Z` 顯示。日期範圍包含在內，且必須不超過 31 個日曆日。此外，第一個日期和時間必須小於從當天起算 90 天。
下列範例示範如何使用 Amazon Pinpoint REST API AWS CLI、 和 查詢行銷活動的分析資料 適用於 Java 的 AWS SDK。您可以使用任何支援的 AWS SDK 來查詢行銷活動的分析資料。這些 AWS CLI 範例已針對 Microsoft Windows 格式化。針對 Unix、Linux 和 macOS，請將插入點 (^) 行接續字元替換成反斜線 (\$1)。
------
#### [ REST API ]
若要使用 Amazon Pinpoint REST API 查詢行銷活動的分析資料，請傳送 HTTP(S) GET 請求到[行銷活動指標](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html) URI。在 URI 中，指定必要路徑參數的適當值：
```
https://endpoint/v1/apps/application-id/campaigns/campaign-id/kpis/daterange/kpi-name
```
其中：
+ *端點*是託管與行銷活動相關聯專案之 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` 是*端點交付*行銷活動指標的 `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` 是*端點交付*行銷活動指標的 `kpi-name` 值，該指標回報有多少個不重複端點，已收到行銷活動傳送的所有訊息。
+ `2019-07-19T00:00:00Z` 是要擷取資料的第一個日期和時間，它是內含日期範圍的一部分。
+ `2019-07-26T23:59:59Z` 則是要擷取資料的最後一個日期和時間，它也是內含日期範圍的一部分。
------
#### [ SDK for Java ]
若要使用 查詢行銷活動的分析資料 適用於 Java 的 AWS SDK，請使用[行銷活動指標 API ](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-campaigns-campaign-id-kpis-daterange-kpi-name.html)的 **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` 是*端點交付*行銷活動指標的 `kpi-name` 值，該指標回報有多少個不重複端點，已收到行銷活動傳送的所有訊息。
+ `2019-07-19T00:00:00Z` 是要擷取資料的第一個日期和時間，它是內含日期範圍的一部分。
+ `2019-07-26T23:59:59Z` 則是要擷取資料的最後一個日期和時間，它也是內含日期範圍的一部分。
------
您傳送查詢後，Amazon Pinpoint 會以 JSON 回應傳回查詢結果。結果的結構會因您查詢的指標而不同。有些指標只會傳回一個值。例如上述範例使用的*端點交付* (`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 年 7 月 19 日 8:00 PM UTC 即以 `2019-07-19T20:00:00Z` 顯示。日期範圍包含在內，且必須不超過 31 個日曆日。此外，第一個日期和時間必須小於從當天起算 90 天。
下列範例示範如何使用 Amazon Pinpoint REST API AWS CLI、 和 查詢行銷活動的分析資料 適用於 Java 的 AWS SDK。您可以使用任何支援的 AWS SDK 來查詢行銷活動的分析資料。這些 AWS CLI 範例已針對 Microsoft Windows 格式化。針對 Unix、Linux 和 macOS，請將插入點 (^) 行接續字元替換成反斜線 (\$1)。
------
#### [ REST API ]
若要使用 Amazon Pinpoint REST API 查詢多個行銷活動的分析資料，請傳送 HTTP(S) GET 請求到[應用程式指標](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) URI。在 URI 中，指定必要路徑參數的適當值：
```
https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name
```
其中：
+ *端點*是託管與行銷活動相關聯專案之 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` 是*端點交付*行銷活動指標的 `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` 是*端點交付*行銷活動指標的 `kpi-name` 值，該指標傳回有多少個不重複端點，已收到每個行銷活動的訊息。
+ `2019-07-19T00:00:00Z` 是要擷取資料的第一個日期和時間，它是內含日期範圍的一部分。
+ `2019-07-26T23:59:59Z` 則是要擷取資料的最後一個日期和時間，它也是內含日期範圍的一部分。
------
#### [ SDK for Java ]
若要使用 查詢多個行銷活動的分析資料 適用於 Java 的 AWS SDK，請使用 [Application Metrics](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` 是*端點交付*行銷活動指標的 `kpi-name` 值，該指標傳回有多少個不重複端點，已收到每個行銷活動的訊息。
+ `2019-07-19T00:00:00Z` 是要擷取資料的第一個日期和時間，它是內含日期範圍的一部分。
+ `2019-07-26T23:59:59Z` 則是要擷取資料的最後一個日期和時間，它也是內含日期範圍的一部分。
------
您傳送查詢後，Amazon Pinpoint 會以 JSON 回應傳回查詢結果。結果的結構會因您查詢的指標而不同。有些指標只會傳回一個值。其他指標則會傳回多個值，並會根據相關欄位為那些值進行分組。若指標傳回多個值，則 JSON 回應會包含欄位，指出使用了哪些欄位來為資料進行分組。
例如上述範例使用的*端點交付 (依行銷活動分組)* (`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 Analytics API 查詢標準指標子集的分析資料，深入了解為專案傳送的交易訊息的成果和互動趨勢。
這些指標每一個都是可測量的值，也稱為「關鍵績效指標 (KPI)」**，其可協助您監控與評估交易訊息的績效。例如您可以使用指標了解自己傳送了多少交易電子郵件或 SMS 訊息，或者有多少訊息已交付給收件人。Amazon Pinpoint 會針對您為專案傳送的所有交易電子郵件和 SMS 訊息，自動收集並彙總相關資料。資料可存放 90 天。
若使用 Amazon Pinpoint Analytics API 查詢資料，可以選擇定義查詢範圍、資料、群組和篩選條件的各種選項。您可以使用參數來執行此作業；這些參數會指定您希望查詢的專案和指標，以及任何您希望套用的日期類型篩選條件。
本主題會提供範例，說明如何選擇這些選項以及查詢專案的交易訊息資料。
## 先決條件
在您查詢交易訊息的分析資料前，收集以下可用於定義查詢的資訊，將會對您有所幫助：
+ **專案 ID** – 傳送訊息的專案的唯一識別符。在 Amazon Pinpoint API 中，此值存放在 `application-id` 屬性內。在 Amazon Pinpoint 主控台上，此值是**所有專案**頁面上的**專案 ID**。
+ **日期範圍** – (選用) 查詢資料日期範圍的第一個和最後一個日期和時間。日期範圍包含在內，且必須不超過 31 個日曆日。此外，也必須從當天起算少於 90 天。若沒有指定日期範圍，Amazon Pinpoint 會自動查詢前 31 個日曆天的資料。
+ **指標** – 要查詢的指標名稱，明確地說就是指標的 `kpi-name` 值。如需支援指標的完整清單及每個指標的 `kpi-name` 值，請參閱 [專案、行銷活動和旅程的標準指標](analytics-standard-metrics.md)。
這也有助於您判斷是否要根據相關欄位對資料進行分組。若您執行此作業，您可以選擇旨在為您自動分組資料的指標，來簡化您的分析和報告。例如 Amazon Pinpoint 提供了多個標準指標，用於回報已交付給收件人的交易 SMS 訊息數。其中一項指標會依日期 (`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 年 9 月 6 日 8:00 PM UTC 即以 `2019-09-06T20:00:00Z` 顯示。日期範圍包含在內，且必須不超過 31 個日曆日。此外，第一個日期和時間必須小於從當天起算 90 天。
下列範例示範如何使用 Amazon Pinpoint REST API AWS CLI、 和 查詢交易電子郵件訊息的分析資料 適用於 Java 的 AWS SDK。您可以使用任何支援的 AWS 開發套件來查詢交易訊息的分析資料。這些 AWS CLI 範例已針對 Microsoft Windows 格式化。針對 Unix、Linux 和 macOS，請將插入點 (^) 行接續字元替換成反斜線 (\$1)。
------
#### [ REST API ]
若要使用 Amazon Pinpoint REST API 查詢交易電子郵件訊息的分析資料，請傳送 HTTP(S) GET 請求到[應用程式指標](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) URI。在 URI 中，指定必要路徑參數的適當值：
```
https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name
```
其中：
+ *端點*是託管專案之 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，請使用 [Application Metrics](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 年 9 月 6 日 8:00 PM UTC 即以 `2019-09-06T20:00:00Z` 顯示。日期範圍包含在內，且必須不超過 31 個日曆日。此外，第一個日期和時間必須小於從當天起算 90 天。
下列範例示範如何使用 Amazon Pinpoint REST API AWS CLI、 和 查詢交易簡訊的分析資料 適用於 Java 的 AWS SDK。您可以使用任何支援的 AWS SDK 來查詢交易訊息的分析資料。這些 AWS CLI 範例已針對 Microsoft Windows 格式化。針對 Unix、Linux 和 macOS，請將插入點 (^) 行接續字元替換成反斜線 (\$1)。
------
#### [ REST API ]
若要透過 Amazon Pinpoint REST API 查詢交易 SMS 訊息的分析資料，請傳送 HTTP(S) GET 請求到[應用程式指標](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-kpis-daterange-kpi-name.html) URI。在 URI 中，指定必要路徑參數的適當值：
```
https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name
```
其中：
+ *端點*是託管專案之 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` 值，該指標傳回日期範圍內每天傳送了多少交易 SMS 訊息。
+ `2019-09-06T00:00:00Z` 是要擷取資料的第一個日期和時間，它是內含日期範圍的一部分。
+ `2019-09-08T23: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 月 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` 值，該指標傳回日期範圍內每天傳送了多少交易 SMS 訊息。
+ `2019-09-06T00:00:00Z` 是要擷取資料的第一個日期和時間，它是內含日期範圍的一部分。
+ `2019-09-08T23:59:59Z` 則是要擷取資料的最後一個日期和時間，它也是內含日期範圍的一部分。
------
#### [ SDK for Java ]
若要使用 查詢交易簡訊的分析資料 適用於 Java 的 AWS SDK，請使用 [Application Metrics](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` 值，該指標傳回日期範圍內每天傳送了多少交易 SMS 訊息。
+ `2019-09-06T00:00:00Z` 是要擷取資料的第一個日期和時間，它是內含日期範圍的一部分。
+ `2019-09-08T23:59:59Z` 則是要擷取資料的最後一個日期和時間，它也是內含日期範圍的一部分。
------
您傳送查詢後，Amazon Pinpoint 會以 JSON 回應傳回查詢結果。結果的結構會因您查詢的指標而不同。有些指標只會傳回一個值。其他指標則會傳回多個值，並依相關欄位分組這些值。若指標傳回多個值，則 JSON 回應會包含欄位，指出使用了哪些欄位來為資料進行分組。
例如上述範例使用的*傳送 (依日期分組)* (`txn-sms-sent-grouped-by-date`) 應用程式指標會傳回多個值 - 在指定的日期範圍內，每天傳送了多少交易 SMS 訊息。本案例的 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 查詢結果
使用 Amazon Pinpoint Analytics API 查詢分析資料時，Amazon Pinpoint 會在 JSON 回應中傳回結果。應用程式指標、行銷活動指標和旅程參與指標的回應資料，符合用於回報 Amazon Pinpoint 分析資料的標準 JSON 結構描述。
這表示您可以使用所選程式設計語言或工具實作自訂的解決方案，查詢一或多個這些指標的資料、擷取每個查詢的結果，然後將結果寫入資料表、物件或其他位置。您接著便可以在該位置使用其他服務或應用程式來使用查詢結果。
例如，您可以：
+ 建置自訂儀表板，定期查詢一組指標，並使用您慣用的資料視覺化框架來顯示結果。
+ 建立報告，查詢適當的指標來追蹤參與率，並在圖表或其他您設計的報告類型中顯示結果。
+ 剖析並將分析資料寫入特定儲存格式，然後將結果移植到長期儲存體解決方案。
請注意，Amazon Pinpoint Analytics API 並非用於建立或儲存任何永久性物件，讓您隨後可以在 Amazon Pinpoint 專案或 Amazon Pinpoint 帳戶中讀取或使用。相反地，API 旨在協助您擷取分析資料，並將該資料傳輸到其他服務和應用程式進行進一步的分析、儲存或報告。部分使用相同的 JSON 回應結構和結構描述處理所有分析資料以執行此作業，分析資料可以以程式設計方式查詢其應用程式指標、行銷活動指標和行程參與指標。
本主題說明應用程式指標、行銷活動指標或行程參與指標查詢之 JSON 回應的結構、物件和欄位。如需行程執行指標或行程活動執行指標查詢之 JSON 回應的欄位相關資訊，請參閱[適用於 Amazon Pinpoint 專案、行銷活動和旅程的標準指標](analytics-standard-metrics.md)。
## JSON 結構
為了協助您剖析和使用查詢結果，Amazon Pinpoint Analytics API 對所有 Amazon Pinpoint 分析資料使用相同的 JSON 回應結構，您可以透過程式化方式查詢應用程式指標、行銷活動指標和旅程參與指標。每個 JSON 回應都會指定定義查詢的值，例如專案 ID (`ApplicationId`)。回應還包括一個 (且只有一個) `KpiResult` 物件。`KpiResult` 物件包含查詢的整體結果集。
每個 `KpiResult` 物件都包含一個 `Rows` 物件。此為物件陣列，包含查詢結果及這些結果值的相關中繼資料。`Rows` 物件的結構和內容具有下列一般特性：
+ 查詢結果的每一列都是個別的 JSON 物件，名為 `Values`，並位於 `Rows` 物件中。例如，如果查詢傳回三個值，則 `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 會傳回該指標的空值。例如：
```
{
"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` 物件都包含一些或所有下列標準物件和欄位，取決於指標。
| 物件或欄位 | Description |
| --- | --- |
| 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)。