查詢交易電子郵件訊息的 Amazon Pinpoint 資料 - Amazon Pinpoint

支援終止通知：2026 年 10 月 30 日， AWS 將結束對 Amazon Pinpoint 的支援。2026 年 10 月 30 日之後，您將無法再存取 Amazon Pinpoint 主控台或 Amazon Pinpoint 資源 (端點、區段、行銷活動、旅程和分析)。如需詳細資訊，請參閱 Amazon Pinpoint 終止支援。注意：與 SMS、語音、行動推播、OTP 和電話號碼驗證相關的 APIs 不受此變更影響，並受 AWS 最終使用者傳訊支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

查詢交易電子郵件訊息的 Amazon Pinpoint 資料

若要查詢為專案傳送的交易電子郵件訊息資料，您可以使用應用程式指標 API 並指定下列必要參數的值：

  • application-id – 專案 ID，即專案的唯一識別符。在 Amazon Pinpoint 中，「專案」和「應用程式」這兩個術語意義相同。

  • kpi-name – 要查詢的指標名稱。此值會說明相關聯的指標，並由兩個以上的術語組成；這些術語都是由小寫的英數字元組成，並以連字號分隔。如需支援指標的完整清單及每個指標的 kpi-name 值，請參閱 專案、行銷活動和旅程的標準指標。

您也可以套用篩選條件，查詢特定日期範圍的資料。若沒有指定日期範圍，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，請將插入點 (^) 行接續字元替換成反斜線 (\)。

REST API

若要使用 Amazon Pinpoint REST API 查詢交易電子郵件訊息的分析資料，請傳送 HTTP(S) GET 請求到應用程式指標 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 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 查詢結果。