レポートの管理

現在、Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントをご確認ください
情報

はじめに

Monetization レポートでは、フォーカスされた使用状況情報とトランザクション アクティビティにアクセスできます。たとえば、特定の期間にトランザクション アクティビティが発生したアプリケーション、デベロッパー、API プロダクト バンドル、API プロダクトを特定できます。収益化では、API の使用状況を追跡する概要レポートまたは詳細レポートを生成できます。

収益化レポートの種類

次の種類の収益化レポートを生成できます。

レポート 説明
請求 特定の請求月のデベロッパーのアクティビティを表示し、料金プランが正しく適用されていることを確認します。
プリペイド残高 プリペイドのデベロッパーが請求月または現在のオープン月に行った残高の補充を確認して、決済代行業者から受け取ったお支払いを調整できるようにします。
収益 一定期間内のデベロッパーのアクティビティと収益を表示することで、デベロッパー(とそのアプリケーション)全体での API プロダクト バンドルとプロダクトのパフォーマンスを分析できます。
バリアンス

2 つの期間でデベロッパーのアクティビティと収益を比較します。これにより、デベロッパー(およびそのアプリケーション)全体での API パッケージとプロダクトのパフォーマンスの上下の傾向を分析できます。

データの保持について

Apigee Edge パブリック クラウドでは、収益化データの保持はプランの利用資格です。収益化の利用資格については、https://cloud.google.com/apigee/specsheets をご覧ください。収益化データを利用資格期間を超えて保持する場合は、Apigee の営業担当者にお問い合わせください。拡張データ保持はリクエストの時点で有効になり、さかのぼって有効にして元のデータ保持期間より前のデータを含めることはできません。

[収益化レポート] ページの使い方

次の手順で [収益受け取りレポート] ページにアクセスします。

Edge

Edge UI を使用して [レポート] ページにアクセスするには:

  1. apigee.com/edge にログインします。
  2. 左側のナビゲーション バーで [Publish] > [Monetization] > [Reports] を選択します。

[レポート] ページが表示されます。

図でハイライト表示されているように、[レポート] ページでは次のことができます。

従来の Edge(Private Cloud)

Classic Edge UI を使用して [レポート] ページにアクセスするには:

  1. http://ms-ip:9000 にログインします。ここで、ms-ip は Management Server ノードの IP アドレスまたは DNS 名です。
  2. 上部のナビゲーション バーで [Monetization] > [Monetization Reports] を選択します。

[レポート] ページが表示されます。

レポートを設定する

以降のセクションで説明するように、UI を使用してレポートを設定します。

レポートを設定する手順

Edge UI または Classice Edge UI を使用してレポートを構成します。

エッジ

Edge UI を使用してレポートを構成するには:

  1. 左側のナビゲーション バーで [Publish] > [Monetization] > [Reports] を選択します。
  2. [+ レポート] をクリックします。
  3. 次の表に定義するレポートの詳細を構成します。
    項目 説明
    名前 レポートの一意の名前。
    説明 レポートの説明。
    レポートタイプ 収益化レポートの種類をご覧ください。
  4. 以下のセクションの説明に沿って、選択したレポートタイプに基づいてレポートの残りの詳細を設定します。
  5. レポート ウィンドウに情報を入力すると、次のことができます。
    • [レポートを保存] をクリックして、レポートの設定を保存します。
    • 詳細レポートの場合のみ、[ジョブを送信] をクリックしてレポートを非同期で実行し、後で結果を取得します。詳しくは、レポートの生成とダウンロードをご覧ください。

    • [CSV として保存] または [ZIP として保存] をクリックして、生成されたレポートをカンマ区切り値(CSV)または CSV を含む圧縮 ZIP ファイルとしてローカルマシンにダウンロードします。レポートのサイズが大きい場合は、ZIP ダウンロードをおすすめします。これにより、効率的にダウンロードできます。

従来の Edge(Private Cloud)

Classic Edge UI を使用してレポートを作成するには:

  1. 上部のナビゲーション バーで [Monetization] > [Monetization Reports] を選択します。
  2. プルダウン メニューで、作成するレポートの種類を選択します。収益化レポートの種類をご覧ください。
  3. [+ 報告] をクリックします。
  4. 選択した請求タイプに基づいてレポートの詳細を次のように構成します。
  5. レポート ウィンドウに情報を入力すると、次のことができます。
    • [名前を付けて保存] をクリックしてレポートの設定を保存し、後でレポートをダウンロードします。
    • 詳細レポートの場合のみ、[ジョブを送信] をクリックしてレポートを非時間実行し、後で結果を取得します。詳しくは、レポートの生成とダウンロードをご覧ください。

    • [CSV 形式でダウンロード] をクリックして、レポートを生成し、カンマ区切り値(CSV)ファイルとしてローカルマシンにダウンロードします。

請求レポートを設定する

レポートを設定する手順に沿って、レポートページに次の情報を入力します。

項目 説明
請求月

レポートの請求月。

レポートレベル

レポートレベル。有効な値は次のとおりです。

  • 詳細: 各トランザクションが個別の行に表示されます。料金プランが正しく適用されていることを確認できます。概要はありません。
  • 概要: 各 API プロダクトとデベロッパーの合計収益の概要。
プロダクト バンドル

: 従来の Edge UI では、API プロダクト バンドルは API パッケージと呼ばれます。

レポートに含める API プロダクト バンドルを選択します。何も選択していない場合は、すべての API プロダクト バンドルがレポートに含まれます。

このレポートには、選択した API プロダクト バンドルごとに個別の行が表示されます。

概要レポートの場合は、必要に応じて概要表示オプションで [表示しない] をオンにします。その場合、レポートにはすべての(または選択した)API プロダクト バンドルの情報が集計されます(各 API プロダクト バンドルの情報は個別に記載されません)。

商品

レポートに含める API プロダクトを選択します。何も選択していない場合は、すべての API プロダクトがレポートに含まれます。

レポートには、選択した API プロダクトごとに個別の行が表示されます。

概要レポートの場合は、必要に応じて概要表示オプションで [表示しない] をオンにします。この場合、すべての(または選択した)デベロッパーの情報が集計されます(選択した各デベロッパーの情報は個別に表示されません)。

会社

レポートに含める会社を選択します。何も選択しないと、すべての会社がレポートに含まれます。

料金プラン

レポートに含める料金プラン。次の中から 1 つ選択してください。

  • すべての料金プラン: すべての料金プランをレポートに含めます。
  • 標準料金プラン: 標準料金プランのみをレポートに含めます。
  • デベロッパー固有の料金プラン: デベロッパー向けのプランのみをレポートに含めます。

前払い残高レポートの設定

レポートを設定する手順に沿って、レポートページに次の情報を入力します。

項目 説明
請求月

レポートの請求月。

レポートレベル

レポートレベル。有効な値は次のとおりです。

  • 詳細: 残高補充ごとに個別に表示され、決済代行業者から受け取ったお支払いと照合できます。
  • 概要: デベロッパーごとの残高補充の合計金額の概要。
会社

レポートに含める会社を選択します。何も選択しないと、すべての会社がレポートに含まれます。

収益レポートを構成する

レポートを設定する手順に沿って、レポートページに次の情報を入力します。

項目 説明
期間(日)

レポートの期間。次の中から 1 つ選択してください。

  • プリセット: プルダウン メニューから標準期間(先月など)のいずれかを選択します。
  • カスタム: カレンダーのポップアップから、期間の開始日と終了日を選択します。
通貨を選択

レポートの通貨。有効な値は次のとおりです。

  • 現地通貨: レポートの各行は、該当する料金プランを使用して表示されます。つまり、デベロッパーが複数の通貨を使用する計画を策定している場合、1 つのレポートに複数の通貨が含まれている可能性があります。
  • ユーロ: レポート内の現地通貨の取引は、ユーロに換算されて表示されます。
  • 英国ポンド: レポート内の現地通貨による取引は、ポンドで換算されて表示されます。
  • 米ドル: レポート内の現地通貨による取引は米ドルに換算されて表示されます。
レポートレベル

レポートレベル。有効な値は次のとおりです。

  • 詳細: 各取引が 1 行に 1 つずつ表示されます。概要はありません。
  • 概要: 選択したパラメータに応じて、各 API プロダクトとデベロッパーの合計収益の概要。
プロダクト バンドル

: 従来の Edge UI では、API プロダクト バンドルは API パッケージと呼ばれます。

レポートに含める API プロダクト バンドルを選択します。何も選択していない場合は、すべての API プロダクト バンドルがレポートに含まれます。

このレポートには、選択した API プロダクト バンドルごとに個別の行が表示されます。

概要レポートの場合は、必要に応じて概要表示オプションで [表示しない] をオンにします。その場合、レポートにはすべての(または選択した)API プロダクト バンドルの情報が集計されます(各 API プロダクト バンドルの情報は個別に記載されません)。

商品

レポートに含める API プロダクトを選択します。何も選択していない場合は、すべての API プロダクトがレポートに含まれます。

レポートには、選択した API プロダクトごとに個別の行が表示されます。

概要レポートの場合は、必要に応じて概要表示オプションで [表示しない] をオンにします。この場合、すべての(または選択した)デベロッパーの情報が集計されます(選択した各デベロッパーの情報は個別に表示されません)。

会社

レポートに含める会社を選択します。何も選択しないと、すべての会社がレポートに含まれます。

サマリー レポートの場合は、必要に応じて、[サマリー表示オプション] セクションで [表示しない] をオンにします。この場合、レポートにはすべての(または選択した)企業の情報が集計されます(選択した各会社の情報を個別に表示することはできません)。

アプリ

レポートに含めるアプリケーションを選択してください。何も選択していない場合は、すべてのアプリケーションがレポートに含まれます。

レポートには、選択したアプリケーションごとに行が表示されます。

サマリー レポートの場合は、必要に応じて、[サマリー表示オプション] セクションで [表示しない] をオンにします。この場合、レポートにはすべての(または選択された)アプリケーションの情報が集約されます(選択した各アプリケーションの情報は個別にリストされません)。

概要表示オプション

レポートで列をグループ化して表示する順序です。グループ内のそのセクションの相対的な順序を示す数値を選択します(1 は最初のグループ化)。たとえば以下の例では、レポートをパッケージ別、プロダクト別、デベロッパー別、アプリケーション別にグループ化しています。

セクションを表示しない場合は、[表示しない] を選択し、残りのフィールドを順番に選択します。1 つのセクションの相対的な順序を変更したり、レポートにセクションを表示しないように選択したりすると、順序が自動的に更新されます。

収益概要レポートにカスタム トランザクション属性を含める

トランザクション記録ポリシーを使用すると、トランザクションからカスタム属性データをキャプチャでき、それらのカスタム属性を収益概要レポートに含めることができます。組織の MINT.SUMMARY_CUSTOM_ATTRIBUTES プロパティを設定して、収益化データベースのテーブルに含まれるカスタム属性のデフォルト セットを定義します。

この機能を使用するには、検討と計画が必要です。以下の考慮事項を確認してください。

クラウドをご利用の場合は、Apigee Edge サポートに連絡してプロパティの設定を依頼してください。Apigee Edge for Private Cloud をご利用の場合は、システム管理者の認証情報を使用して、PUT リクエストを使用して次の API にフラグを設定します。

curl -u email:password -X PUT -H "Content-type:application/xml" http://host:port/v1/o/{myorg} -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isMonetizationEnabled">true</Property>
        <Property name="MINT.SUMMARY_CUSTOM_ATTRIBUTES">[&quot;partner_id&quot;,&quot;tax_source&quot;]</Property>
        <Property name="features.topLevelDevelopersAreCompanies">false</Property>
    </Properties>
</Organization>"

この例では、API 呼び出しによって機能が有効になり、partner_id 列と tax_source 列が収益化データベースに追加されます。API 呼び出しのカスタム属性の配列は URL エンコードされます。

カスタム取引属性をレポートに含める際の考慮事項

  • API で属性名を作成する前に、使用する属性名を決めてください。これらはデータベースの列名であり、カスタム属性データは常にそこに保存されます。
  • 次の画像に示すように、各トランザクション記録ポリシーには 10 個のカスタム属性スロットを使用できます。レポートに含める商品全体で、同一の属性名と位置は、まったく同じものを使用します。たとえば、次のトランザクション記録ポリシーでは、カスタム属性 partner_idtax_source はそれぞれボックス 4 と 5 を占めています。レポートに含めるプロダクトのすべての取引記録ポリシーで、担当者の名前と位置を使用する必要があります。

機能を有効にした後にカスタム属性を概要収益レポートに含めるには、MintCriteriatransactionCustomAttributes を追加して Report API を使用します。条件設定オプションをご覧ください。

差異レポートの設定(非推奨)

レポートを設定する手順に沿って、レポートページに次の情報を入力します。

項目 説明
期間(日)

レポートの期間。次の中から 1 つ選択してください。

  • プリセット: プルダウン メニューから標準期間(先月など)のいずれかを選択します。
  • カスタム: カレンダーのポップアップから、期間の開始日と終了日を選択します。
パッケージ

レポートに含める API パッケージ。次の中から 1 つ選択してください。

  • すべて: すべての API パッケージがレポートに含まれます。
  • 選択済み: リストが表示され、レポートに含める API パッケージを選択できます。パッケージを選択しない場合は、すべてのパッケージがレポートに含まれます。

このレポートには、選択した API パッケージごとに行が 1 行表示されます。

サマリー レポートの場合、オプションとして [サマリー表示オプション] セクションで [表示しない(パッケージ)] をオンにできます。その場合、レポートにはすべての(または選択した)API パッケージの情報が集計されます(各 API パッケージの情報は個別に記載されません)。

商品

レポートに含める API プロダクト。次の中から 1 つ選択してください。

  • すべて: レポート内のすべての API プロダクトが含まれます。
  • 選択済み: リストが表示され、レポートに含める商品を選択できます。商品を選択しない場合は、すべての商品がレポートに含まれます。

レポートには、選択した API プロダクトごとに個別の行が表示されます。

概要レポートの場合は、必要に応じて [概要表示オプション] セクションで [表示しない(商品)] をオンにできます。その場合、レポートにはすべての(または選択した)API プロダクトに関する情報が集計されます(各 API プロダクトに関する情報は個別に記載されません)。

会社

レポートに含める会社。次の中から 1 つ選択してください。

  • すべて: レポート内のすべての会社が表示されます。
  • 選択済み: リストが表示され、レポートに含める会社を選択できます。会社を選択しない場合は、すべての会社がレポートに含まれます。

レポートには、選択した会社ごとに行が表示されます。

サマリー レポートの場合は、オプションとして [サマリー表示オプション] セクションで [表示しない(会社)] をオンにできます。この場合、レポートにはすべての(または選択した)会社の情報が集計されます(選択した各会社の情報を個別に表示することはできません)。

アプリ

レポートに含めるアプリケーション。次の中から 1 つ選択してください。

  • すべて: レポート内のすべてのアプリケーションが含まれます。
  • 選択済み: リストが表示され、ここからレポートに含めるアプリケーションを選択できます。アプリケーションを選択しない場合は、すべてのアプリケーションがレポートに含まれます。

レポートには、選択したアプリケーションごとに行が表示されます。

サマリー レポートの場合は、オプションとして [サマリー表示オプション] セクションで [表示しない(アプリケーション)] をオンにできます。この場合、レポートにはすべての(または選択された)アプリケーションの情報が集約されます(選択した各アプリケーションの情報は個別にリストされません)。

通貨

レポートの通貨。有効な値は次のとおりです。

  • 現地通貨: レポートの各行は、該当する料金プランを使用して表示されます。つまり、デベロッパーが複数の通貨を使用する計画を策定している場合、1 つのレポートに複数の通貨が含まれている可能性があります。
  • EUR: レポート内の現地通貨での取引はユーロに換算されて表示されます。
  • GPB: レポート内の現地通貨による取引は、ポンドで換算されて表示されます。
  • USD: レポート内の現地通貨の取引は米ドルに換算されて表示されます。
概要表示オプション

レポートで列をグループ化して表示する順序です。グループ内のそのセクションの相対的な順序を示す数値を選択します(1 は最初のグループ化)。たとえば以下の例では、レポートをパッケージ別、プロダクト別、デベロッパー別、アプリケーション別にグループ化しています。

セクションを表示しない場合は、[表示しない] を選択し、残りのフィールドを順番に選択します。1 つのセクションの相対的な順序を変更したり、レポートにセクションを表示しないように選択したりすると、順序が自動的に更新されます。

レポートの生成とダウンロード

レポートを作成した後、レポートの結果を CSV 形式または ZIP ファイル形式でダウンロードできます。 CSV ファイルまたは ZIP ファイルは同期的または非同期的に生成できます。

  • 同期レポートの場合、レポート リクエストを実行すると、分析サーバーが応答を返すまでリクエストがブロックされます。しかし、レポートで大量のデータ(たとえば、数百 GB)を処理する必要がある場合は、タイムアウトで同期レポートが失敗する可能性があります。

    概要レポートレベルでは、同期生成のみがサポートされます。

  • 非同期レポートの場合、レポート リクエストを実行し、結果は後で受け取ります。次のような状況では、非同期クエリ処理が適切な代替手段になることがあります。

    • レポートの分析と作成に長い時間がかかる場合。
    • グループ化のディメンションが多いなど、クエリを複雑にする制約のあるデータを分析する場合。
    • 一部のユーザーや組織のデータ量が大幅に増加したことが判明したときにクエリを管理する場合。

    詳細レポートレベルでは、非同期生成がサポートされています。

CSV 形式または ZIP ファイル形式でレポートを生成してダウンロードするには、次のいずれかの作業を行います。

  1. [レポート] ページにアクセスします。
  2. ダウンロードするレポートにカーソルを合わせます。
  3. [変更] 列で、次のいずれかをクリックします。

    1. CSV ファイル アイコン アイコンまたは zip ファイル アイコン アイコン(概要レポートの場合)レポートは CSV ファイルまたは ZIP ファイルに同期して保存されます。
    2. ジョブを送信(詳細レポートの場合)。非同期ジョブが開始します。
      1. [変更済み] 列でジョブのステータスをモニタリングします。

        レポートをダウンロードできる状態になると、ディスク アイコンが表示されます。

        レポートをダウンロードできる状態になると、ディスク イメージが表示されます。
      2. ジョブが完了したら、ディスク アイコンをクリックしてレポートをダウンロードします。

次に、請求概要レポートの CSV ファイルの例を示します。

レポートを編集する

レポートを編集する方法は次のとおりです。

  1. [レポート] ページにアクセスします
  2. 編集するレポートにカーソルを合わせ、操作メニューで をクリックします。
  3. 必要に応じて、レポート構成を更新します。
  4. [レポートを更新] をクリックして、更新したレポート設定を保存します。

レポートの削除

レポートを削除するには:

  1. [レポート] ページにアクセスします
  2. 削除するレポートにカーソルを合わせます。
  3. 操作メニューで をクリックします。

API を使用して収益化レポートを管理する

以降のセクションでは、API を使用して収益化レポートを管理する方法について説明します。

API を使ってレポートを設定する

組織全体のレポートを構成するには、/organizations/{org_name}/report-definitions に POST リクエストを発行します。

特定のデベロッパーに関するレポートを設定するには、/organizations/{org_name}/developers/{dev_id}/report-definitions に POST リクエストを発行します。ここで、{dev_id} はデベロッパーの ID です。

リクエストを行う際は、レポートの名前とタイプを指定する必要があります。タイプは、BILLINGREVENUEVARIANCE(非推奨)、PREPAID_BALANCE のいずれかです。また、mintCriteria プロパティで条件を指定して、レポートを詳細に構成することもできます。幅広い条件を指定できます。これにより、レポートを柔軟に構成できます。条件として指定できる項目は次のとおりです。

  • 請求または前払い残高レポートの場合、レポートの請求月
  • 収益レポートの場合、購入取引、請求取引、払い戻しなど、レポートの対象となる取引の種類
  • 前払い残高レポートの場合、レポートの適用先のデベロッパー
  • 収益レポートの場合、レポートが適用される API プロダクト バンドル(または API パッケージ)、プロダクト、料金プラン、アプリケーション
  • 収益レポートまたは差異レポートの場合、レポートに適用できる通貨
  • 請求レポート、プリペイド残高レポート、収益レポートの場合、レポートが概要レポートか詳細レポートか
  • 収益概要レポートの場合は、レポートにカスタム トランザクション属性を含める

レポート条件の一覧については、レポート設定オプションをご覧ください。

次のサンプルでは、2015 年 7 月のトランザクション アクティビティを要約した収益レポートを作成します。このレポートは、transactionTypes プロパティで指定されたさまざまな取引タイプを含み、特に Payment API プロダクト バンドルと Payment API プロダクトに適用されます。レポート定義では特定のデベロッパーまたはアプリケーションは指定されていないため、レポートはすべてのデベロッパーとアプリケーションに適用されます。また、currencyOption プロパティが LOCAL に設定されているため、レポートの各行は該当する料金プランの通貨で表示されます。また、groupBy プロパティは、レポートの列を PACKAGE、PRODUCT、DEVELOPER、APPLICATION、RATEPLAN(レポートに料金プランの名前と ID を含む)の順序でグループ化することを指定します。

$ curl -H "Content-Type: application/json" -X POST -d \
'{
      "name": "July 2015 revenue report",
      "description": " July 2015 revenue report for Payment product",
      "type": "REVENUE",     
      "mintCriteria":{
         "fromDate":"2015-07-01 00:00:00",
         "toDate":"2015-08-01 13:35:00",
         "showTxDetail":true,
         "showSummary":true,
         "transactionTypes":[
            "PURCHASE",
            "CHARGE",
            "REFUND",
            "CREDIT",
            "SETUPFEES",
            "TERMINATIONFEES",
            "RECURRINGFEES"
         ],
         "monetizationPackageIds":[
            "payment"
         ],
         "productIds":[
            "payment"
         ],
         "currencyOption":"LOCAL",
         "groupBy":[
            "PACKAGE",
            "PRODUCT",
            "DEVELOPER",
            "APPLICATION",
            "RATEPLAN"
         ]
      }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions" \
-u email:password

次の例では、デベロッパーの DEV FIVE の 2015 年 6 月のアクティビティを示す詳細な請求レポートを作成しています。

$ curl -H "Content-Type:application/json" -X POST -d \
'{
      "name": "June billing report, DEV FIVE",
      "description": "June billing report, DEV FIVE",
      "type": "BILLING",      
      "mintCriteria":{
         "billingMonth": "JUNE",
         "billingYear": 2015,
         "showTxDetail":true,
         "showSummary":false,         
         "currencyOption":"LOCAL"         
      },
      "devCriteria":[{
         "id":"RtHAeZ6LtkSbEH56",
         "orgId":"myorg"}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xU/report-definitions" \
-u email:password

API を使用してレポート設定を表示する

組織の特定のレポート構成またはすべてのレポート構成を表示できます。また、個々のデベロッパーのレポート構成を表示することもできます。

組織の特定のレポート構成を表示するには、GET リクエストを /organizations/{org_name}/report-definitions/{report_definition_id} に送信します。ここで、{report_definition_id} は特定のレポート構成の ID です(ID は、レポート構成を作成するとレスポンスで返されます)。例:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/1f7fa53b-de5a-431d-9438-62131e1396c5" \
-u email:password

組織のすべてのレポート構成を表示するには、/organizations/{org_name}/report-definitions に GET リクエストを発行します。

次のクエリ パラメータを渡して、結果のフィルタリングや並べ替えを行うことができます。

クエリ パラメータ 説明
all すべての API プロダクト バンドルを返すかどうかを指定するフラグ。false に設定した場合、1 ページあたりで返される API プロダクト バンドルの数は size クエリ パラメータで定義されます。デフォルトは false です。
size ページごとに返される API プロダクト バンドルの数です。デフォルトは 20 です。all クエリ パラメータが true に設定されている場合、このパラメータは無視されます。
page 返すページの数(コンテンツがページ分けされている場合)。all クエリ パラメータが true に設定されている場合、このパラメータは無視されます。
sort 情報の並べ替えに使用するフィールド。all クエリ パラメータが true に設定されている場合、このパラメータは無視されます。デフォルトは UPDATED:DESC です。

たとえば、次の例では、組織のレポート構成が返され、取得できるレポート構成は最大 5 個に制限されています。

$ curl -H "Accept:application/json" -X GET \ 
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions?size=5" \ 
-u email:password

レスポンスは次のようになります(レスポンスの一部のみが表示されます)。

{
  "reportDefinition" : [ {
    "description" : "Test revenue report",
    "developer" : null,
    "id" : "1f7fa53b-de5a-431d-9438-62131e1396c5",
    "lastModified" : "2015-08-27 15:44:03",
    "mintCriteria" : {
      "asXorg" : false,
      "currencyOption" : "LOCAL",
      "fromDate" : "2015-07-01 00:00:00",
      "groupBy" : [ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN" ],
      "monetizationPackageIds" : [ "payment" ],
      "productIds" : [ "payment" ],
      "showRevSharePct" : false,
      "showSummary" : true,
      "showTxDetail" : true,
      "showTxType" : false,
      "toDate" : "2015-08-01 00:05:00",
      "transactionTypes" : [ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ]
    },
    "name" : "Test revenue report",
    "organization" : {
      ...
    },
    "type" : "REVENUE"
  }, {
    "description" : "June billing report, DEV FIVE",
    "developer" : null,
    "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb",
    "lastModified" : "2015-08-27 17:13:20",
    "mintCriteria" : {
      "asXorg" : false,
      "billingMonth" : "JUNE",
      "billingYear" : 2015,
      "currencyOption" : "LOCAL",
      "showRevSharePct" : false,
      "showSummary" : false,
      "showTxDetail" : true,
      "showTxType" : false
    },
    "name" : "June billing report, DEV FIVE",
    "organization" : {
      ...
    },
    "type" : "BILLING"
  } ],
  "totalRecords" : 2
}

特定のデベロッパーのレポート構成を表示するには、GET リクエストを /organizations/{org_name}/developers/{dev_id}/report-definitions に送信します。ここで、{dev_id} はデベロッパーの ID です。リクエストを行うときに、上記のクエリ パラメータを指定してデータのフィルタリングや並べ替えを行うことができます。

たとえば、次の例では、特定のデベロッパーのレポート構成を返し、レポート名でレスポンスを並べ替えます。

$ curl -H "Accept:application/json" -X GET \ 
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xUreport-definitions?sort=name" \ 
-u email:password

API を使用してレポート設定を更新する

レポート構成を更新するには、PUT リクエストを /organizations/{org_name}/report-definitions/{report_definition_id} に送信します。ここで、{report_definition_id} は特定のレポート構成を示す ID です。更新を行う際は、更新された構成値とレポート構成の ID をリクエスト本文で指定する必要があります。たとえば、次のリクエストでは、レポートが概要レポートに更新されます(更新されたプロパティがハイライト表示されています)。

$ curl -H "Content-Type: application/json" -X PUT -d \
 '{
       "id": "fedac696-ce57-469b-b62c-a77b535fd0eb",
       "name": "June billing report, DEV FIVE",
       "description": "June billing report, DEV FIVE",
       "type": "BILLING",      
       "mintCriteria":{      
         "billingMonth": "JUNE",
         "billingYear": 2015,
         "showTxDetail":false,
         "showSummary":true    
        }     
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \
-u email:password

レスポンスは次のようになります(レスポンスの一部のみが表示されます)。

{
 "description" : "June billing report, DEV FIVE",
  "developer" : null,
  "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb",
  "lastModified" : "2015-08-27 17:47:29",
  "mintCriteria" : {
    "asXorg" : false,
    "billingMonth" : "JUNE",
    "billingYear" : 2015,
    "showRevSharePct" : false,
    "showSummary" : true,
    "showTxDetail" : false,
    "showTxType" : false
  },
  "name" : "June billing report, DEV FIVE",
  "organization" : {
    ... 
  },
  "type" : "BILLING"
}

API を使用してレポート構成を削除する

レポート構成を削除するには、/organizations/{org_namer}/report-definitions/{report_definition_id} に DELETE リクエストを発行します。ここで、{report_definition_id} は、削除するレポート構成の ID です。例:

$ curl -H "Accept:application/json" -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \
-u email:password

API を使用してレポートを生成する

レポートを構成したら、レポートをカンマ区切り値(CSV)ファイル形式で生成して表示できます。

レポートを生成するには、organizations/{org_id}/{report_type} に POST リクエストを発行します。ここで、{report_type} には、生成するレポートの種類を指定します。型は次のとおりです。

  • billing-reports
  • revenue-reports
  • prepaid-balance-reports
  • variance-reports
さらに、特定のデベロッパー向けに収益レポートを生成することもできます。詳細については、デベロッパー向けに収益レポートを生成するをご覧ください。

たとえば、請求レポートを生成するには、organizations/{org_name}/billing-reports に POST リクエストを発行します。

どのタイプのレポートでも、リクエストの本文でレポートの検索条件を指定します。mintCriteria プロパティを使用して検索条件を指定します。詳しくは、条件の設定オプションをご覧ください。

たとえば、次のリクエストでは、レポートの開始日と終了日、トランザクション タイプなどのさまざまな条件に基づいて収益レポートが検索されます。

$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \
'{
      "fromDate":"2015-07-01 00:00:00",
      "toDate":"2015-08-01 13:35:00",
      "showTxDetail":true,
      "showSummary":true,                
      "transactionTypes":[
        "PURCHASE",
        "CHARGE",
        "REFUND",
        "CREDIT",
        "SETUPFEES",
        "TERMINATIONFEES",
        "RECURRINGFEES"
      ],
      "currencyOption":"LOCAL",
      "groupBy":[
        "PACKAGE",
        "PRODUCT",
        "DEVELOPER",
        "APPLICATION",
        "RATEPLAN"]
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \
-u email:password

見つかった場合、収益レポートは CSV ファイル形式で生成されます。以下にレポート出力の例を示します。

Reporting Period:,From:,2015-07-01,  To:,2015-07-31
API Product:,All
Developer:,All
Application:,All
Currency:,Local
Type of Report:,Summary Revenue Report

Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate,
Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,

API を使用してデベロッパーのカスタム属性を収益レポートに含める

収益レポートの場合のみ、デベロッパーに対してカスタム属性が定義されている場合は、レポートにカスタム属性を含めることができます。アプリ デベロッパーの管理で説明されているように、組織にデベロッパーを追加する際にカスタム属性を定義します。

収益レポートにカスタム属性を含めるには、organizations/{org_name}/revenue-reports に POST リクエストを発行し、リクエスト本文に devCustomAttributes 配列を含めます。

"devCustomAttributes": [
    "custom_attribute1",
    "custom_attribute2",
    ...
]

注: devCustomAttributes 配列には、事前定義された MINT_* 属性と ADMIN_* 属性を指定しないでください。

たとえば次の例には、BILLING_TYPESFIDORG_EXT の 3 つのカスタム属性がレポートに含まれています(デベロッパーに対して定義されている場合)。

$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \
'{
      "fromDate":"2015-07-01 00:00:00",
      "toDate":"2015-08-01 13:35:00",
      "showTxDetail":true,
      "showSummary":true,                
      "transactionTypes":[
        "PURCHASE",
        "CHARGE",
        "REFUND",
        "CREDIT",
        "SETUPFEES",
        "TERMINATIONFEES",
        "RECURRINGFEES"
      ],
      "currencyOption":"LOCAL",
      "groupBy":[
        "PACKAGE",
        "PRODUCT",
        "DEVELOPER",
        "APPLICATION",
        "RATEPLAN"
      ],
      "devCustomAttributes": [
         "BILLING_TYPE",
         "SFID",
         "ORG_EXT"
      ]
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \
-u email:password

以下に、2 つのカスタム属性の値を含むレポート出力の例を示します。

Reporting Period:,From:,2015-07-01,  To:,2015-07-31
API Product:,All
Developer:,All
Application:,All
Currency:,Local
Type of Report:,Summary Revenue Report

Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate,BILLING_TYPE,SFID,ORG_EXT 
Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,

API を使用して取引アクティビティを報告する

組織のトランザクション アクティビティを表示するには、/organizations/{org_name}/transaction-search に POST リクエストを発行します。リクエストを行う場合は、取得の条件を指定する必要があります。条件として指定できる項目は次のとおりです。

  • トランザクションが発行された 1 つ以上の API プロダクトの ID。
  • トランザクションの請求年と請求年。
  • 取引を発行したデベロッパー。
  • 取引の種類(購入や設定手数料など)。
  • トランザクションのステータス(成功、失敗など)。

条件の一覧については、条件設定オプションをご覧ください。

次の例では、請求月 2015 年 6 月に特定のデベロッパーが発行したトランザクションが返されます。

$ curl -H "Content-Type:application/json" -X POST -d \
 '{        
    "billingMonth": "JUNE",
    "billingYear": 2015,
    "devCriteria": [{
      "id": "RtHAeZ6LtkSbEH56",
      "orgId":"myorg"}],
    "transactionTypes": ["PURCHASE", "CHARGE", "SETUPFEES"],
    "transactionStatus": ["SUCCESS", "FAILED"]
    }'
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/transaction-search \
-u email:password

また、特定の期間内にトランザクション アクティビティが発生したアプリケーション、デベロッパー、API プロダクト バンドル、API プロダクトを特定することもできます。この情報は、オブジェクトのタイプごとに個別に表示できます。たとえば、指定した開始日と終了日の間に、収益化対象の API プロダクト バンドル内の API にアクセスしたアプリケーションに関する情報を確認できます。

トランザクション アクティビティに関する情報を表示するには、次のいずれかのリソースに GET リクエストを発行します。

リソース 戻り値
/organizations/{org_name}/applications-with-transactions

トランザクションを伴うアプリケーション

/organizations/{org_name}/developers-with-transactions

取引を行っているデベロッパー

/organizations/{org_name}/products-with-transactions

取引がある商品

/organizations/{org_name}/packages-with-transactions

取引を含む API プロダクト バンドル(または API パッケージ)

リクエストを発行する際に、日付範囲の開始日と終了日をクエリ パラメータとして指定する必要があります。たとえば、次のリクエストでは、2015 年 8 月中にトランザクションがあったデベロッパーが返されます。

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers-with-transactions?START_DATE=2015-08-01&END_DATE=2015-08-31" \
-u email:password

レスポンスは次のようになります(レスポンスの一部のみが表示されます)。

{
  "developer" : [ {
    "address" : [ {
      "address1" : "Dev Five Address",
      "city" : "Pleasanton",
      "country" : "US",
      "id" : "0917f15f-9521-4e69-9376-07aa7b7b32ca",
      "isPrimary" : true,
      "state" : "CA",
      "zip" : "94588"
    } ],
    "approxTaxRate" : 0.0900,
    "billingType" : "POSTPAID",
    "broker" : false,
    "developerRole" : [ ],
    "email" : "dev5@myorg.com",
    "hasSelfBilling" : false,
    "id" : "tJZG6broTpGGGeLV",
    "legalName" : "DEV FIVE",
    "name" : "Dev Five",
    "organization" : {
      ...
    },
    "registrationId" : "dev5",
    "status" : "ACTIVE",
    "type" : "UNTRUSTED"
  }, {
    "address" : [ {
      "address1" : "Dev Seven Address",
      "city" : "Pleasanton",
      "country" : "US",
      "id" : "f86d8c9f-6ed1-4323-b050-6adf494096c9",
      "isPrimary" : true,
      "state" : "CA",
      "zip" : "94588"
    } ],
    "approxTaxRate" : 0.0900,
    "billingType" : "POSTPAID",
    "broker" : false,
    "developerRole" : [ ],
    "email" : "dev7@myorg.com",
    "hasSelfBilling" : false,
    "id" : "VI3l8m8IPAvJTvjS",
    "legalName" : "DEV SEVEN",
    "name" : "Dev Seven",
    "organization" : {
      ...
    },
    "registrationId" : "dev7",
    "status" : "ACTIVE",
    "type" : "UNTRUSTED"
  }, ...
  ]
}

API のレポート設定オプション

API では、次のレポート構成オプションを使用できます。

名前 説明 デフォルト 必須 / 任意
name

レポートの名前。

なし
description

レポートの説明。

なし ×
mintCriteria

レポートを設定する条件。詳しくは、条件設定オプションをご覧ください。

なし ×
type

レポートのタイプ。値は次のいずれかになります。

  • BILLING
  • REVENUE
  • VARIANCE
  • PREPAID_BALANCE
なし

条件設定オプション

mintCriteria プロパティを介したレポートでは、次の設定オプションを使用できます。

名前 説明 デフォルト 必須 / 任意
appCriteria

レポートに含める特定のアプリケーションの ID と組織。このプロパティを指定しなかった場合、すべてのアプリケーションがレポートに含まれます。

なし ×
billingMonth

注: このプロパティは収益レポートでは無効です。

レポートの請求月(7 月など)。

なし
billingYear

注: このプロパティは収益レポートでは無効です。

レポートの請求年(2015 年など)。

なし
currCriteria

レポートに含める特定の通貨の ID と組織。このプロパティが指定されていない場合は、サポートされているすべての通貨がレポートに含まれます。

なし ×
currencyOption

レポートの通貨。有効な値は次のとおりです。

  • LOCAL。レポートの各行は、該当する料金プランを使用して表示されます。つまり、デベロッパーが異なる通貨を使用する計画を策定している場合、1 つのレポートに複数の通貨が存在することがあります。
  • EUR。現地通貨での取引はユーロに換算されて表示されます。
  • GPB。現地通貨での取引は英国ポンドで変換されて表示されます。
  • USD。現地通貨での取引は米ドルで変換されて表示されます。
なし ×
devCriteria

デベロッパー ID(メールアドレス)、レポートに含める特定のデベロッパーの組織名。このプロパティが指定されていない場合、すべてのデベロッパーがレポートに含まれます。例:

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]
                
なし ×
devCustomAttributes

注: このプロパティは収益レポートにのみ適用されます。

レポートに含めるカスタム属性(デベロッパーに対して定義されている場合)。次に例を示します。

"devCustomAttributes": [
    "custom_attribute1",
    "custom_attribute2",
    ...
]

注: devCustomAttributes 配列には、事前定義された MINT_* 属性と ADMIN_* 属性を指定しないでください。

なし ×
fromDate

注: このプロパティは、収益、差異、トランザクションのアクティビティ レポートにのみ適用されます。

レポートの開始日(UTC)。

なし 収益レポートの場合は必須。他のレポートタイプでは不要です。
groupBy

レポートで列をグループ化する順序です。有効な値は次のとおりです。

  • APPLICATION
  • BALANCE
  • DEVELOPER
  • ORG
  • PACKAGE
  • PRODUCT
  • RATEPLAN
なし ×
monetizationPackageId

レポートに含める 1 つ以上の API プロダクト バンドルの ID。このプロパティが指定されていない場合、すべての API プロダクト バンドルがレポートに含まれます。

注: トランザクション アクティビティ(/transaction-search)を表示している場合、このプロパティは無効です。

なし ×
pkgCriteria

レポートに含める特定の API プロダクト バンドルの ID と組織。このプロパティが指定されていない場合、すべての API プロダクト バンドルがレポートに含まれます。このプロパティは、monetizationpackageIds プロパティの代わりに指定できます。

注: トランザクション アクティビティ(/transaction-search)を表示している場合、このプロパティは無効です。

なし ×
prevFromDate

注: このプロパティは差異レポートにのみ適用されます。

前の期間の開始日(UTC)。現在のレポートと比較する、前の期間のレポートを作成します。

なし ×
prevToDate

注: このプロパティは差異レポートにのみ適用されます。

前の期間の終了日(UTC)。現在のレポートと比較する、前の期間のレポートを作成します。

なし ×
prodCriteria

レポートに含める特定の API プロダクトの ID と組織。このプロパティが指定されていない場合、すべての API プロダクトがレポートに含まれます。このプロパティは、productIds プロパティの代わりに指定できます。

注: トランザクション アクティビティ(/transaction-search)を表示している場合、このプロパティは無効です。

なし ×
productIds

レポートに含める 1 つ以上の API プロダクトの ID。このプロパティが指定されていない場合、すべての API プロダクトがレポートに含まれます。

API プロダクト ID は org-name@@@product-name として指定する必要があります。例: "productIds": ["myorg@@@myproduct", "myorg@@@myproduct2"]

なし ×
pricingTypes

レポートに含める料金プランの料金タイプ。有効な値は次のとおりです。

  • REVSHARE。収益分配プラン。
  • REVSHARE_RATECARD。収益分配率とレート表の料金プラン。
  • RATECARD。料金表プラン。

このプロパティが指定されていない場合、すべての料金タイプの料金プランがレポートに含まれます。

なし ×
ratePlanLevels

レポートに含める料金プランのタイプ。有効な値は次のとおりです。

  • DEVELOPER。デベロッパー料金プラン。
  • STANDARD。標準料金プラン。

このプロパティが指定されていない場合、デベロッパー固有の料金プランと標準料金プランの両方がレポートに含まれます。

なし ×
showRevSharePct

レポートに収益分配率を表示するかどうかを指定するフラグ。有効な値は次のとおりです。

  • true。収益分配率の割合を表示します。
  • false。収益分配率は表示されません。
なし ×
showSummary

レポートがサマリーかどうかを指定するフラグ。有効な値は次のとおりです。

  • true。レポートは概要です。
  • false。レポートは概要ではありません。
なし ×
showTxDetail

注: このプロパティは収益レポートにのみ適用されます。

レポートに取引単位の詳細を表示するかどうかを指定するフラグ。有効な値は次のとおりです。

  • true。取引単位の明細を表示します。
  • false。トランザクション単位の情報は表示されません。
なし ×
showTxType

各取引の種類をレポートに表示するかどうかを指定するフラグ。有効な値は次のとおりです。

  • true。各取引のタイプを表示します。
  • false。各取引の種類を表示しないでください。
なし ×
toDate

注: このプロパティは、収益、差異、トランザクションのアクティビティ レポートにのみ適用されます。

レポートの終了日(UTC)。

このレポートには、指定した日付の前日までに収集されたデータが含まれます。指定した終了日に収集されたレポートデータはレポートから除外されます。 たとえば、料金プランを 2016 年 12 月 31 日に期限切れにする場合は、toDate 値を 2017-01-01 に設定する必要があります。この場合、レポートには 2016 年 12 月 31 日までのレポートデータが含まれ、2017 年 1 月 1 日のレポートデータは除外されます。

なし 収益レポートの場合は必須。他のレポートタイプでは不要です。
transactionStatus

レポートに含める取引のステータス。有効な値は次のとおりです。

  • SUCCESS。取引が正常に完了しました。
  • DUPLICATE。取引が重複しています。これらの取引は無視してかまいません。Apigee ランタイムから評価サーバーへのデータ パイプラインは、フォールト トレラントにするために重複トランザクションを生成する場合があります。また、収益化でこれらのトランザクションが重複として認識されてマークされる場合があります。
  • FAILED。取引の失敗。このステータスは、前提条件の検証が失敗した場合にトリガーされます。次に例を示します。
    • デベロッパーが料金プランを購入していないのに評価を試みました。これは、Monetization Limits Check ポリシーが構成されていない場合に発生することがあります。
    • 割り当てを超過したが、呼び出しは継続される。これは、Monetization Limits Check ポリシーが構成されていない場合に発生することがあります。
    • カスタム属性ベースのプランに除外カスタム属性値が送信されました。
  • INVALID_TSC。取引が無効です。このステータスは、txProviderStatus ランタイム条件が API プロダクト バンドルレベルで指定された成功基準と一致しない場合にトリガーされます。
  • REVIEW。確認が必要な取引。このステータスは、値が構成されていない収益範囲内にある場合に、柔軟な収益分配の料金プランでトリガーされます。
なし ×
transactionCustomAttributes

概要収益レポートに含めるカスタム取引属性。この機能は組織で有効にする必要があります。詳しくは、収益概要レポートにカスタム トランザクション属性を含めるをご覧ください。

なし ×
transactionTypes

レポートに含めるトランザクションのタイプ。有効な値は次のとおりです。

このプロパティが指定されていない場合、すべての取引タイプがレポートに含まれます。

なし ×