**支援終止通知：**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 分析 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)。