トランザクションメッセージの Amazon Pinpoint 分析データのクエリ - Amazon Pinpoint

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

トランザクションメッセージの Amazon Pinpoint 分析データのクエリ

Amazon Pinpoint コンソールの分析ページを使用することに加えて、Amazon Pinpoint Analytics API を使用して、プロジェクトに送信されたトランザクションメッセージの配信とエンゲージメントの傾向についてのインサイトを提供する標準メトリクスのサブセットについて分析データをクエリできます。

メトリクスは測定可能な値で、重要業績評価指標 (KPI) とも呼ばれ、トランザクションメッセージのパフォーマンスを監視および評価するのに役立ちます。例えば、メトリクスを使用して、送信した E メールのトランザクション数、送信した SMS メッセージ数、または受取人に配信されたメッセージ数を調べることができます。Amazon Pinpoint は、プロジェクトに送信するすべての E メールのトランザクションおよび SMS メッセージについて、このデータを自動的に収集し、集計します。これは、90 日間データを保存します。

Amazon Pinpoint 分析 API を使用してデータをクエリする場合、クエリの範囲、データ、グループ化、フィルターを定義するさまざまなオプションを選択できます。これを行うには、適用する日付ベースのフィルターに加えて、クエリするプロジェクトとメトリクスを指定するパラメータを使用します。

このトピックでは、これらのオプションを選択し、プロジェクトに関するトランザクションメッセージングデータをクエリする方法の例を説明します。

前提条件

トランザクションメッセージの分析データをクエリする前に、クエリの定義に使用する、次の情報を収集すると役立ちます。

  • Project ID – メッセージの送信元のプロジェクトの一意の識別子。Amazon Pinpoint API では、この値は application-id プロパティに保存されます。Amazon Pinpoint コンソールでは、この値は すべてのプロジェクト ページでProject ID として表示されます。

  • Date range – オプションで、データを問い合せる日付範囲の最初と最後の日付と時刻。日付範囲は包括的であり、31日以内に制限する必要があります。また、最初の日付と時刻は、現在の日付から 90 日未満である必要があります。日付範囲を指定しない場合、Amazon Pinpoint は過去 31 暦日のデータを自動的にクエリします。

  • Metric – クエリするメトリクスの名前。具体的には、メトリクスの kpi-name 値。サポートされているメトリクスの完全なリストと各メトリクスの kpi-name 値については、「標準メトリクス」を参照してください。

また、関連するフィールドでデータをグループ化するかどうかを決定することもできます。する場合、データを自動的にグループ化するように設計されたメトリクスを選択することで、分析とレポート作成を簡素化できます。例えば、Amazon Pinpoint には、受信者に配信されたトランザクション SMS メッセージの数を報告する標準メトリクスがいくつか用意されています。これらのメトリクスの 1 つは、データを日付ごとに自動的にグループ化します (txn-sms-delivered-grouped-by-date)。別のメトリクスでは、データが国またはリージョンによって自動的にグループ化されます (txn-sms-delivered-grouped-by-country)。3 番目のメトリクスは、単純に一つの値、つまり受信者に配信されたメッセージングの数を返します (txn-sms-delivered)。必要な方法でデータをグループ化する標準メトリクスが見つからない場合は、必要なデータを返す一連のクエリを開発できます。その後、クエリ結果を手動で分類したり、デザインするカスタムグループに結合できます。

最後に、クエリするデータにアクセスする権限があることを確認することが重要です。詳細については、「Amazon Pinpoint 分析データのクエリ実行用の IAM ポリシー」を参照してください。

トランザクション E メールメッセージのデータのクエリ

プロジェクトに送信されたトランザクション E メールメッセージのデータをクエリするには、Application Metrics API を使用して、次の必須パラメータの値を指定します。

  • application-id – プロジェクトの一意の識別子であるプロジェクト ID。Amazon Pinpoint では、プロジェクトアプリケーションという用語は同じ意味です。

  • kpi-name – クエリするメトリクスの名前。この値は、関連するメトリクスを記述し、ハイフンで区切られた小文字の英数字で構成される 2 つ以上の用語で構成されます。サポートされているメトリクスの完全なリストと各メトリクスの kpi-name 値については、「標準メトリクス」を参照してください。

また、特定の日付範囲のデータをクエリするフィルターを適用することもできます。日付範囲を指定しない場合、Amazon Pinpoint は過去 31 暦日のデータを返します。異なる日付でデータをフィルタリングするには、サポートされている日付範囲パラメータを使用して、日付範囲の最初と最後の日時を指定します。値は拡張 ISO 8601 形式で、協定世界時 (UTC) を使用する必要があります (例: 2019-09-06T20:00:00Z は、2019 年 9 月 6 日午後 8 時 (UTC) )。日付範囲は包括的であり、31 日以内に制限する必要があります。また、最初の日付と時刻は、現在の日付から 90 日未満である必要があります。

次の例は、Amazon Pinpoint REST API、AWS CLI、および AWS SDK for Java を使用して、トランザクション E メールメッセージの分析データをクエリする方法を示しています。任意のサポートされている AWS SDK を使用して、トランザクションメッセージの分析データをクエリできます。これらの AWS CLI の例は、Microsoft Windows 用にフォーマットされています。Unix、Linux、macOS の場合は、キャレット (^) 行継続文字をバックスラッシュ (\) に置き換えます。

REST API

Amazon Pinpoint REST API を使用してトランザクション E メールメッセージの分析データをクエリするには、HTTP(S) GET リクエストを Application Metrics URI に送信します。URI で、必要なパスパラメータに次の適切な値を指定します。

https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name

各パラメータの意味は次のとおりです。

  • endpoint は、プロジェクトをホストする AWS リージョンの Amazon Pinpoint エンドポイントです。

  • application-id は、プロジェクトの一意の識別子です。

  • kpi-name は、クエリするメトリクスの kpi-name 値です。

すべてのパラメータは、URL エンコードする必要があります。

特定の日付範囲のデータをクエリするフィルターを適用するには、URI に start-time および end-time クエリパラメータと値を追加します。これらのパラメータを使用すると、データを取得する日付範囲の最初と最後の日付と時刻(両端を含む)を、拡張 ISO 8601 形式で指定できます。パラメータを区切るには、アンパサンド (&) を使用します。

例えば、次のリクエストは、2019 年 9 月 6 日から 2019 年 9 月 13 日までプロジェクトに送信されたトランザクション E メールメッセージの数を取得します。

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 値で、プロジェクトのために送信されたトランザクション E メールメッセージの数を報告するメトリクスです。

  • 2019-09-06T00:00:00Z は、端の値を含む日付範囲の一部として、データを取得する最初の日付と時刻です。

  • 2019-09-13T23:59:59Z は、端の値を含む日付範囲の一部として、データを取得する最後の日付と時刻です。

AWS CLI

AWS CLI を使用してトランザクション E メールメッセージの分析データをクエリするには、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 日までプロジェクトに送信されたトランザクション E メールメッセージの数を取得します。

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 値で、プロジェクトのために送信されたトランザクション E メールメッセージの数を報告するメトリクスです。

  • 2019-09-06T00:00:00Z は、端の値を含む日付範囲の一部として、データを取得する最初の日付と時刻です。

  • 2019-09-13T23:59:59Z は、端の値を含む日付範囲の一部として、データを取得する最後の日付と時刻です。

SDK for Java

AWS SDK for Java を使用してトランザクション E メールメッセージの分析データを照会するには、Application Metrics APIGetApplicationDateRangeKpiRequest メソッドを使用します。必要なパラメータに適切な値を指定します。

GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest() .withApplicationId("applicationId") .withKpiName("kpiName")

実行する条件は以下のとおりです。

  • applicationId は、プロジェクトの一意の識別子です。

  • kpiName は、クエリするメトリクスの kpi-name 値です。

特定の日付範囲のデータをクエリするフィルターを適用するには、startTime および endTime パラメータと値をクエリに含めます。これらのパラメータを使用すると、データを取得する日付範囲の最初と最後の日付と時刻(両端を含む)を、拡張 ISO 8601 形式で指定できます。例えば、次のリクエストは、2019 年 9 月 6 日から 2019 年 9 月 13 日までプロジェクトに送信されたトランザクション E メールメッセージの数を取得します。

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 値で、プロジェクトのために送信されたトランザクション E メールメッセージの数を報告するメトリクスです。

  • 2019-09-06T00:00:00Z は、端の値を含む日付範囲の一部として、データを取得する最初の日付と時刻です。

  • 2019-09-13T23:59:59Z は、端の値を含む日付範囲の一部として、データを取得する最後の日付と時刻です。

クエリを送信すると、Amazon Pinpoint はクエリ結果を JSON レスポンスで返します。結果の構造は、クエリしたメトリクスによって異なります。一部のメトリクスは 1 つの値しか返しません。例えば、前述の例で使用されている、送信 (txn-emails-sent) アプリケーションメトリクスは、1 つの値 (プロジェクトから送信されたトランザクション E メールメッセージの数) を返します。この場合、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 レスポンスにはデータのグループ化に使用されたフィールドを示すフィールドが含まれます。

クエリ結果の構造の詳細については、「クエリ結果の使用」を参照してください。

トランザクション SMS メッセージのデータのクエリ

プロジェクトに送信されたトランザクション SMS メッセージのデータをクエリするには、Application Metrics API を使用して、次の必須パラメータの値を指定します。

  • application-id – プロジェクトの一意の識別子であるプロジェクト ID。Amazon Pinpoint では、プロジェクトアプリケーションという用語は同じ意味です。

  • kpi-name – クエリするメトリクスの名前。この値は、関連するメトリクスを記述し、ハイフンで区切られた小文字の英数字で構成される 2 つ以上の用語で構成されます。サポートされているメトリクスの完全なリストと各メトリクスの kpi-name 値については、「標準メトリクス」を参照してください。

また、特定の日付範囲のデータをクエリするフィルターを適用することもできます。日付範囲を指定しない場合、Amazon Pinpoint は過去 31 暦日のデータを返します。異なる日付でデータをフィルタリングするには、サポートされている日付範囲パラメータを使用して、日付範囲の最初の日時と最後の日時を指定します。値は拡張 ISO 8601 形式で、協定世界時 (UTC) を使用する必要があります (例: 2019-09-06T20:00:00Z は、2019 年 9 月 6 日午後 8 時 (UTC) )。日付範囲は包括的であり、31 日以内に制限する必要があります。また、最初の日付と時刻は、現在の日付から 90 日未満である必要があります。

次の例は、Amazon Pinpoint REST API、AWS CLI 、および AWS SDK for Java を使用して、トランザクション SMS メッセージの分析データをクエリする方法を示しています。任意のサポートされている AWS SDK を使用して、トランザクションメッセージの分析データをクエリできます。これらの AWS CLI の例は、Microsoft Windows 用にフォーマットされています。Unix、Linux、macOS の場合は、キャレット (^) 行継続文字をバックスラッシュ (\) に置き換えます。

REST API

Amazon Pinpoint REST API を使用してトランザクション SMS メッセージの分析データをクエリするには、HTTP(S) GET リクエストを Application Metrics URI に送信します。URI で、必要なパスパラメータに次の適切な値を指定します。

https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name

各パラメータの意味は次のとおりです。

  • endpoint は、プロジェクトをホストする AWS リージョンの Amazon Pinpoint エンドポイントです。

  • application-id は、プロジェクトの一意の識別子です。

  • kpi-name は、クエリするメトリクスの kpi-name 値です。

すべてのパラメータは、URL エンコードする必要があります。

特定の日付範囲のデータを取得するフィルターを適用するには、URI に start-time および end-time クエリパラメータと値を追加します。これらのパラメータを使用すると、データを取得する日付範囲の最初と最後の日付と時刻(両端を含む)を、拡張 ISO 8601 形式で指定できます。パラメータを区切るには、アンパサンド (&) を使用します。

例えば、次のリクエストは、2019 年 9 月 6 日から 2019 年 9 月 8 日まで毎日送信されたトランザクション SMS メッセージの数を取得します。

https://pinpoint.us-east-1.amazonaws.com/v1/apps/1234567890123456789012345example/kpis/daterange/txn-sms-sent-grouped-by-date?start-time=2019-09-06T00:00:00Z&end-time=2019-09-08T23:59:59Z

実行する条件は以下のとおりです。

  • pinpoint.us-east-1.amazonaws.com は、プロジェクトをホストする AWS リージョンの Amazon Pinpoint エンドポイントです。

  • 1234567890123456789012345example は、プロジェクトの一意の識別子です。

  • txn-sms-sent-grouped-by-date は、日付アプリケーションメトリクスでグループ化された送信kpi-name 値で、日付範囲の各日に送信されたトランザクション SMS メッセージの数を返すメトリクスです。

  • 2019-09-06T00:00:00Z は、端の値を含む日付範囲の一部として、データを取得する最初の日付と時刻です。

  • 2019-09-08T23:59:59Z は、端の値を含む日付範囲の一部として、データを取得する最後の日付と時刻です。

AWS CLI

AWS CLI を使用してトランザクション SMS メッセージの分析データをクエリするには、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 月 8 日まで毎日送信されたトランザクション SMS メッセージの数を取得します。

C:\> aws pinpoint get-application-date-range-kpi ^ --application-id 1234567890123456789012345example ^ --kpi-name txn-sms-sent-grouped-by-date ^ --start-time 2019-09-06T00:00:00Z ^ --end-time 2019-09-08T23:59:59Z

実行する条件は以下のとおりです。

  • 1234567890123456789012345example は、プロジェクトの一意の識別子です。

  • txn-sms-sent-grouped-by-date は、日付アプリケーションメトリクスでグループ化された送信kpi-name 値で、日付範囲の各日に送信されたトランザクション SMS メッセージの数を返すメトリクスです。

  • 2019-09-06T00:00:00Z は、端の値を含む日付範囲の一部として、データを取得する最初の日付と時刻です。

  • 2019-09-08T23:59:59Z は、端の値を含む日付範囲の一部として、データを取得する最後の日付と時刻です。

SDK for Java

AWS SDK for Java を使用してトランザクション SMS メッセージの分析データをクエリするには、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 月 8 日まで毎日送信されたトランザクション SMS メッセージの数を取得します。

GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest() .withApplicationId("1234567890123456789012345example") .withKpiName("txn-sms-sent-grouped-by-date") .withStartTime(Date.from(Instant.parse("2019-09-06T00:00:00Z"))) .withEndTime(Date.from(Instant.parse("2019-09-08T23:59:59Z")));

実行する条件は以下のとおりです。

  • 1234567890123456789012345example は、プロジェクトの一意の識別子です。

  • txn-sms-sent-grouped-by-date は、日付アプリケーションメトリクスでグループ化された送信kpi-name 値で、日付範囲の各日に送信されたトランザクション SMS メッセージの数を返すメトリクスです。

  • 2019-09-06T00:00:00Z は、端の値を含む日付範囲の一部として、データを取得する最初の日付と時刻です。

  • 2019-09-08T23:59:59Z は、端の値を含む日付範囲の一部として、データを取得する最後の日付と時刻です。

クエリを送信すると、Amazon Pinpoint はクエリ結果を JSON レスポンスで返します。結果の構造は、クエリしたメトリクスによって異なります。一部のメトリクスは 1 つの値しか返しません。他のメトリクスは複数の値を返し、関連するフィールドでそれらの値をグループ化します。メトリクスが複数の値を返す場合、JSON レスポンスにはデータのグループ化に使用されたフィールドを示すフィールドが含まれます。

例えば、前述の例で使用されている、日付 (txn-sms-sent-grouped-by-date) アプリケーションのメトリクスでグループ化された送信は、複数の値(与えられた日付範囲の各日中に送信されたトランザクション SMS のメッセージ数)を返します。この場合、JSON レスポンスは次のようになります。

{ "ApplicationDateRangeKpiResponse":{ "ApplicationId":"1234567890123456789012345example", "EndTime":"2019-09-08T23:59:59Z", "KpiName":"txn-sms-sent-grouped-by-date", "KpiResult":{ "Rows":[ { "GroupedBys":[ { "Key":"Date", "Type":"String", "Value":"2019-09-06" } ], "Values":[ { "Key":"TxnSmsSent", "Type":"Double", "Value":"29.0" } ] }, { "GroupedBys":[ { "Key":"Date", "Type":"String", "Value":"2019-09-07" } ], "Values":[ { "Key":"TxnSmsSent", "Type":"Double", "Value":"35.0" } ] }, { "GroupedBys":[ { "Key":"Date", "Type":"String", "Value":"2019-09-08" } ], "Values":[ { "Key":"TxnSmsSent", "Type":"Double", "Value":"10.0" } ] } ] }, "StartTime":"2019-09-06T00:00:00Z" } }

この場合、GroupedBys フィールドは値が暦日 (Date) でグループ化されていることを示しています。これにより、以下のように処理されます。

  • 29 件のメッセージが 2019 年 9 月 6 日に送信されました。

  • 35 件のメッセージが 2019 年 9 月 7 日に送信されました。

  • 10 件のメッセージが 2019 年 9 月 8 日に送信されました。

クエリ結果の構造の詳細については、「クエリ結果の使用」を参照してください。