レポートを管理する

Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントをご覧ください。

はじめに

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

収益化レポートの種類

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

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

2 つの異なる期間にデベロッパーが作成したアクティビティと収益を比較することで、デベロッパー(とそのアプリケーション)全体にわたって API パッケージやプロダクトのパフォーマンスの増減を分析できます。

データ保持について

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

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

以下の説明に従って、[収益化レポート] ページにアクセスします。

エッジ

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

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

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

図に示すように、[レポート] ページでは次のことができます。

Classic Edge(プライベート クラウド)

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

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

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

レポートを設定する

次のセクションの説明に沿って、管理画面でレポートを設定します。

レポートを設定する手順

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

エッジ

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

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

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

Classic Edge(プライベート クラウド)

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

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

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

請求レポートを構成する

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

Field 説明
請求月

レポートの請求月。

レポートレベル

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

  • Detail: 各取引が別々の行に表示され、料金プランが正しく適用されていることを確認できます。要約はありません。
  • サマリー: 各 API プロダクトとデベロッパーの総収益の概要が表示されます。
プロダクト バンドル

: Classic Edge UI では、API プロダクト バンドルを API パッケージと呼びます。

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

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

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

プロダクト

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

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

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

会社

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

料金プラン

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

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

前払い残高レポートの構成

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

Field 説明
請求月

レポートの請求月。

レポートレベル

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

  • 詳細: 各残高の補充が個別に表示され、決済代行業者から受け取った支払いを調整できます。
  • 概要: 各デベロッパーの残高の詰め替えの合計額です。
会社

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

収益レポートの構成

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

Field 説明
期間(日)

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

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

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

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

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

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

: Classic Edge UI では、API プロダクト バンドルを API パッケージと呼びます。

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

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

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

プロダクト

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

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

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

会社

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

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

アプリ

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

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

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

サマリー表示オプション

列がグループ化されてレポートに表示される順序。グループ内のそのセクションの相対的な順序を示す数値を選択します(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 を占有します。名前は、商品がレポートに含まれるように、すべての取引記録ポリシーにおける名前と場所である必要があります。

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

バリアンス レポートの構成(非推奨)

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

Field 説明
期間(日)

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

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

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

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

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

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

プロダクト

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

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

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

概要レポートの場合は、[概要表示オプション] セクションで [表示しない](プロダクト)を選択できます。この場合、レポートではすべての API プロダクト(または選択した API プロダクト)の情報が集約されます(個々の API プロダクトに関する情報が個別に表示されることはありません)。

会社

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

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

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

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

アプリ

レポートに含めるアプリケーション。次の中から 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":[
            "paymentorg-1@@@payment"
         ],
         "currencyOption":"LOCAL",
         "groupBy":[
            "PACKAGE",
            "PRODUCT",
            "DEVELOPER",
            "APPLICATION",
            "RATEPLAN"
         ]
      }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions" \
-u email:password

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

$ 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 1 つのページで返される 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" : [ "paymentorg-1@@@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
}

特定のデベロッパーのレポート構成を表示するには、/organizations/{org_name}/developers/{dev_id}/report-definitions に GET リクエストを発行します。ここで、{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 説明 デフォルト 必須 / 任意
name

レポートの名前。

なし
description

レポートの説明。

なし ×
mintCriteria

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

なし ×
type

レポートのタイプ。次のいずれかの値を指定できます。

  • BILLING
  • REVENUE
  • VARIANCE
  • PREPAID_BALANCE
なし

条件設定オプション

mintCriteria プロパティを使用すると、次の設定オプションを使用できます。

Name 説明 デフォルト 必須 / 任意
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 月までのレポートデータが含まれます(2017 年 1 月 1 日のレポートデータは含まれません)。

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

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

  • SUCCESS。正常な取引。
  • DUPLICATE。送信が重複しています。これらの取引は無視できます。Apigee ランタイムから評価サーバーへのデータ パイプラインは、フォールト トレランスと収益化のために認識され重複としてマークされるトランザクションの重複を生成することがあります。
  • FAILED。取引が失敗しました。このステータスは、前提条件の検証で不合格になるとトリガーされます。例:
    • デベロッパーが料金プランを購入していなくても、評価が行われました。これは、収益化の上限チェック ポリシーが設定されていない場合に発生する可能性があります。
    • 割り当てを超過したが、呼び出しが続行される。これは、収益化の上限チェック ポリシーが設定されていない場合に発生する可能性があります。
    • カスタム属性ベースのプランに負のカスタム属性値が送信されました。
  • INVALID_TSC。取引が無効です。このステータスは、txProviderStatus ランタイム条件が API プロダクト バンドルレベルで指定された成功基準と一致しない場合にトリガーされます。
  • REVIEW。審査が必要な取引。このステータスは、値が収益分配率の設定されていない範囲内である場合に、柔軟な収益分配率のプランでトリガーされます。
なし ×
transactionCustomAttributes

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

なし ×
transactionTypes

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

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

なし ×