サポート終了通知： 2026 年 10 月 30 日、 AWS は Amazon Pinpoint のサポートを終了します。2026 年 10 月 30 日以降、Amazon Pinpoint コンソールまたは Amazon Pinpoint リソース (エンドポイント、セグメント、キャンペーン、ジャーニー、分析) にアクセスできなくなります。詳細については、Amazon Pinpoint のサポート終了」を参照してください。注： SMS、音声、モバイルプッシュ、OTP、電話番号の検証に関連する APIs は、この変更の影響を受けず、 AWS エンドユーザーメッセージングでサポートされています。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amazon Pinpoint 分析 JSON クエリ結果を使用する

Amazon Pinpoint Analytics API を使用して分析データをクエリすると、Amazon Pinpoint は JSON レスポンスで結果を返します。アプリケーションメトリクス、キャンペーンメトリクス、およびジャーニーエンゲージメントメトリクスの場合、レスポンスのデータは、Amazon Pinpoint 分析データをレポートするための標準 JSON スキーマに準拠します。

つまり、選択したプログラミング言語またはツールを使用して、1 つ以上のこれらのメトリクスのデータをクエリし、各クエリの結果を取得して、結果をテーブル、オブジェクト、またはその他の場所に書き込むカスタムソリューションを実装できます。その後、別のサービスまたはアプリケーションを使用して、その場所でクエリ結果を操作できます。

例えば、以下のことが可能です。

Amazon Pinpoint Analytics API は、Amazon Pinpoint プロジェクトや Amazon Pinpoint アカウントで後で読み込んだり使用したりできる永続オブジェクトを作成または保存するようには設計されていないことに注意してください。その代わりに、API は、分析データを取得し、そのデータを他のサービスやアプリケーションに転送して、さらに分析、保存、レポート作成を行うのに役立つように設計されています。これは、アプリケーションメトリクス、キャンペーンメトリクス、およびジャーニーエンゲージメントメトリクスに対してプログラミングによりクエリを実行できるすべての分析データに対して同じ JSON レスポンス構造とスキーマを使用して部分的に行います。

このトピックでは、アプリケーションメトリクス、キャンペーンメトリクス、またはジャーニーエンゲージメントメトリクスのクエリに対する JSON 応答の構造、オブジェクト、および項目について説明します。ジャーニー実行メトリクスまたはジャーニーアクティビティ実行メトリクスのクエリに対する JSON レスポンスのフィールドについては、「Amazon Pinpoint プロジェクト、キャンペーン、ジャーニーに適用される標準メトリクス」を参照してください。

JSON の構造

クエリ結果の解析と使用を支援するために、Amazon Pinpoint Analytics API では、アプリケーションメトリクス、キャンペーンメトリクス、およびジャーニーエンゲージメントメトリクスをプログラミングによりクエリを実行できるすべての Amazon Pinpoint 分析データに対して同じ JSON レスポンス構造を使用します。各 JSON レスポンスでは、プロジェクト ID (ApplicationId) など、クエリを定義した値を指定します。レスポンスには、1 つ（1 つだけ）の KpiResult オブジェクトも含まれます。KpiResult オブジェクトには、クエリの結果セット全体が含まれます。

各 KpiResult オブジェクトには Rows オブジェクトが含まれます。これは、クエリ結果とその結果の値に関する関連メタデータを含むオブジェクトの配列です。Rows オブジェクトの構造と内容には、次の一般的な特性があります。

これらの一般的な特性以外にも、Rows オブジェクトの構造と内容はメトリクスによって異なります。これは、Amazon Pinpoint が、単一値メトリクスと複数値メトリクスの 2 種類のメトリクスをサポートするためです。

単一値のメトリクスは、累積値を 1 つだけ提供します。例えば、キャンペーンのすべての実行によって受取人に配信されたメッセージの割合が挙げられます。複数値のメトリクスは、複数の値を提供し、それらの値を関連するフィールド別にグループ化します。例えば、キャンペーンの実行ごとに受取人に配信されたメッセージの割合を、キャンペーンの実行ごとにグループ化して示します。

メトリクスが単一値メトリクスか複数値メトリクスかは、メトリクスの名前を参照するとすばやく判断できます。名前に grouped-by が含まれていない場合は、単一値メトリクスです。含まれている場合は、複数値メトリクスです。プログラミングによりクエリを実行できるメトリクスの完全なリストについては、「Amazon Pinpoint プロジェクト、キャンペーン、ジャーニーに適用される標準メトリクス」を参照してください。

単一値メトリクス

単一値メトリクスの場合、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 個の一意のエンドポイントにメッセージを配信したことを示しています。

単一値メトリクスのクエリ結果が null (0 以上でない) の場合、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 オブジェクトには、1 つ以上の GroupedBy オブジェクトも含まれます。クエリ結果には、Values オブジェクトごとに 1 つの 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 日までの間で、プロジェクトの 3 つのキャンペーンで一意のエンドポイントにメッセージを配信したという応答が示されます。これらのキャンペーンそれぞれの配信数の内訳は次のとおりです。

オブジェクトおよびフィールドの一般的な構造は次のとおりです。

特定のプロジェクト、キャンペーン、またはその他のリソースに対する、複数値メトリクスのクエリ結果が null（ゼロ以下）の場合、Amazon Pinpoint はリソースにオブジェクトまたはフィールドを返しません。複数値メトリクスのクエリ結果が、すべてのリソースで null の場合、Amazon Pinpoint は空の Rows オブジェクトを返します。

JSON オブジェクトとフィールド

プロジェクト ID (ApplicationId) などのクエリを定義した値を指定することに加えて、アプリケーションメトリクス、キャンペーンメトリック、またはジャーニーエンゲージメントメトリクスのクエリに対する各 JSON レスポンスには、KpiResult オブジェクトが含まれます。このオブジェクトには、クエリの全体的な結果セットが含まれ、この結果を解析して、別のサービスまたはアプリケーションに分析データを送信できます。各 KpiResult オブジェクトには、メトリクスにより、次の標準オブジェクトおよびフィールドの一部またはすべてが含まれます。

ジャーニー実行メトリクスまたはジャーニーアクティビティ実行メトリクスのクエリに対する JSON レスポンスのフィールドについては、「Amazon Pinpoint プロジェクト、キャンペーン、ジャーニーに適用される標準メトリクス」を参照してください。