Amazon Pinpoint 分析クエリ結果の使用 - Amazon Pinpoint

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

Amazon Pinpoint 分析クエリ結果の使用

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 オブジェクト内にある 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 の標準的な分析メトリクス」を参照してください。

単一値メトリクス

単一値メトリクスの場合、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.KeyGroupedBys.Value フィールド (CampaignId) に指定されたグループ化値を保存するプロパティまたはフィールドの名前。

  • GroupedBys.TypeGroupedBys.Value フィールド (String) で指定された値のデータ型。

  • GroupedBys.ValueGroupedBys.Key フィールド(キャンペーン ID)で指定された、データのグループ化に使用されたフィールドの実際の値。

  • Values.Key – 値が Values.Value フィールド (UniqueDeliveries) で指定されるメトリクスのフレンドリ名。

  • Values.TypeValues.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 の標準的な分析メトリクス」を参照してください。