**サポート終了通知:** 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 スキーマに準拠します。
つまり、選択したプログラミング言語またはツールを使用して、1 つ以上のこれらのメトリクスのデータをクエリし、各クエリの結果を取得して、結果をテーブル、オブジェクト、またはその他の場所に書き込むカスタムソリューションを実装できます。その後、別のサービスまたはアプリケーションを使用して、その場所でクエリ結果を操作できます。
例えば、以下のことが可能です。
+ 一連のメトリクスを定期的にクエリし、好みのデータ可視化フレームワークを使用して結果を表示するカスタムダッシュボードを構築します。
+ 適切なメトリクスをクエリし、その結果をグラフまたはユーザーが設計する他の種類のレポートに表示することで、エンゲージメント率を追跡するレポートを作成します。
+ 解析データを解析して特定のストレージ形式に書き込み、結果を長期ストレージソリューションに移植します。
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`) など、クエリを定義した値を指定します。レスポンスには、1 つ（1 つだけ）の `KpiResult` オブジェクトも含まれます。`KpiResult` オブジェクトには、クエリの結果セット全体が含まれます。
各 `KpiResult` オブジェクトには `Rows` オブジェクトが含まれます。これは、クエリ結果とその結果の値に関する関連メタデータを含むオブジェクトの配列です。`Rows` オブジェクトの構造と内容には、次の一般的な特性があります。
+ クエリ結果の各行は、`Rows` オブジェクト内にある `Values`という別個の JSON オブジェクトです。例えば、クエリが 3 つの値を返す場合、`Rows` オブジェクトには 3 つの `Values` オブジェクトが含まれます。各 `Values` オブジェクトには、クエリの個別の結果が含まれます。
+ クエリ結果の各列は、適用される `Values` オブジェクトのプロパティです。列の名前は、`Values` オブジェクトの `Key` フィールドに保存されます。
+ グループ化されたクエリ結果の場合、各 `Values` オブジェクトには関連付けられた `GroupedBys` オブジェクトがあります。`GroupedBys` オブジェクトは、結果をグループ化するために使用されたフィールドを示します。また、関連付けられた `Values` オブジェクトのグループ化値も提供します。
+ メトリクスのクエリ結果が null の場合、`Rows` オブジェクトは空です。
これらの一般的な特性以外にも、`Rows` オブジェクトの構造と内容はメトリクスによって異なります。これは、Amazon Pinpoint が、*単一値メトリクス*と*複数値メトリクス*の 2 種類のメトリクスをサポートするためです。
*単一値のメトリクス*は、累積値を 1 つだけ提供します。例えば、キャンペーンのすべての実行によって受取人に配信されたメッセージの割合が挙げられます。*複数値のメトリクス*は、複数の値を提供し、それらの値を関連するフィールド別にグループ化します。例えば、キャンペーンの実行ごとに受取人に配信されたメッセージの割合を、キャンペーンの実行ごとにグループ化して示します。
メトリクスが単一値メトリクスか複数値メトリクスかは、メトリクスの名前を参照するとすばやく判断できます。名前に `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 (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 つのキャンペーンで一意のエンドポイントにメッセージを配信したという応答が示されます。これらのキャンペーンそれぞれの配信数の内訳は次のとおりです。
+ キャンペーン `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)」を参照してください。