カスタム属性を使用して料金プランを構成する

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

はじめに

場合によっては、変数やカスタム値に基づくトランザクション カウンタが必要になることがあります。たとえば、次のようなことが必要になる場合があります。

  • API 呼び出しのメッセージで提供された値に基づいて、デベロッパーに変動料金を請求します。たとえば、API リクエストで送信されたバイト数に基づいてアプリ デベロッパーに課金する場合です。
  • 複数の API 呼び出しを 1 つのトランザクションにバンドルします。

料金プランとカスタム属性を使用すると、API 呼び出しのメッセージ内のカウンタとして機能し、トランザクション数と料金の計算に使用される値を識別できます。

カスタム属性を含む次の料金プランがサポートされています。

  • カスタム属性付きのレート表
  • カスタム属性を含む調整可能な通知

料金プランごとに設定できるカスタム属性は 10 個までです。

カスタム属性の計算について

次の表に示すように、カスタム属性値が料金プランの取引数と料金に組み込まれる方法は、課金モデルによって異なります。

充電モデル カスタム属性の計算
定額制とボリューム バンド

custom attribute number * rate = charge to developer

定額の場合、カスタム属性の数値は料金に乗算されるトランザクション数になります。ボリューム バンドの場合、特定の帯域内のトランザクション数がカスタム属性番号で増加し、そのトランザクション数に応じてデベロッパーが課金されます。たとえば、メッセージ内のカスタム属性値が 10 の場合、デベロッパーは 10 トランザクションに対して課金され、10 トランザクションが現在のバンド数に追加されます。デベロッパーの現在の帯域に残りのトランザクションが 6 件しかない場合は、6 にその帯域のレートを掛けます。残りの 4 は次の帯域に進み、その帯域のレートを掛けます。

ボリューム バンドプランで、最後のボリューム バンドに上限(「無制限」ではない)があり、トランザクションがその上限を超えると、次の 2 つの状況が発生します。

バンドル

バンドルはトランザクションではなくグループごとに請求されるため、次の計算が行われます。

custom attribute number = amount added to bundle count

たとえば、メッセージ内のカスタム属性番号が 10 の場合、バンドルで使用されるトランザクションの数に 10 が追加されます。デベロッパーの現在のバンドルにトランザクションが 6 つしか残っていない場合、そのバンドルが充填され、次のバンドル数が 4 ずつ増加します。次のバンドルのレート(存在する場合)が課金されます。

最後のバンドルに上限(「無制限」ではない)があり、トランザクションがその上限を超えると、次の 2 つの状況が発生します。

調整可能な通知

調整可能な通知の場合、次の計算が行われます。

custom attribute number = amount added to transaction count

たとえば、メッセージ内のカスタム属性番号が 10 の場合、トランザクションの合計数に 10 が追加されます。

料金プランがカスタム属性値を取得する場所

API プロダクト バンドルの Transaction Recording ポリシーにより、収益化に対してメッセージ内のカスタム属性値の場所を指定します。カスタム属性は、API プロダクト バンドルのトランザクション記録ポリシーの [Custom Attributes] セクションで定義します。

次に、カスタム属性を定義してトランザクション記録ポリシーを含む API プロダクト バンドルを作成した後に、料金プランでそのカスタム属性を選択できます。

大まかなフローは次のとおりです。

  1. API プロダクトを追加するときにカスタム属性を定義します。
  2. プロダクトを含む API プロダクト バンドルを作成します。
    API プロダクト バンドルのトランザクション記録ポリシーに、料金プランの定義に使用するカスタム属性を追加します。
  3. API プロダクト バンドルのタイプのレート表または調整可能な通知の料金プランを作成し、カスタム評価パラメータを指定します。

次の図は、トランザクション記録ポリシーで定義されたカスタム属性と料金表プラン構成の関係を示しています。カスタム属性の料金プランの関係がある調整可能な通知も似ていますが、ボリューム バンドの値は適用されません。

メッセージにカスタム属性値を生成する方法

トランザクション記録ポリシーは、レスポンス ヘッダー、レスポンス本文、レスポンス内の事前定義フロー変数など、複数の場所でカスタム属性値を検索できます。(成功のレスポンスを受け取るまで取引は正式ではないため、リクエストは選択できません)。次の例は、数値を含むレスポンス ヘッダーをメッセージに追加する方法を示しています。いずれの場合も、Assign Message ポリシーを変数と組み合わせて使用します。

レスポンス ヘッダーにリクエスト ペイロード サイズを追加する

各メッセージ リクエストには、リクエスト ペイロードのバイト数を格納する client.received.content.length 変数があります。Assign Message ポリシーをプロキシ エンドポイントのレスポンスに接続することで、長さの値を含む messageSize というレスポンス ヘッダーを生成できます。

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="messageSize">{client.received.content.length}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

ヘッダーにアプリのカスタム属性値を追加する

ほぼ同じように、アプリのカスタム属性の値を使用してヘッダーを生成できます。たとえば、次のように、各デベロッパー アプリに apprating というカスタム属性を含めたとします。

Verify API Key ポリシー(収益化に必要)を使用すると、この値は verifyapikey.{policy_name}.apprating という変数に格納されます。Proxy Endpoint レスポンスに適用されている Assign Message ポリシーを使用すると、アプリの apprating 値を含む apprating というヘッダーを生成できます。

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="apprating">{verifyapikey.Verify-API-Key-1.apprating}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

料金プランの設定

上記のカスタム属性の設定以外は、料金プランは通常どおりに設定します(カスタム属性のない料金プランの場合)。ただし、次の要件を満たす必要があります。

管理画面を使用してカスタム属性で料金表プランを設定する

以降のセクションで説明するように、Edge UI または Classic Edge UI を使用して、カスタム属性で料金表プランを構成します。

エッジ

Edge UI を使用してカスタム属性で料金表プランを構成するには:

  1. API プロダクトを追加するときにカスタム属性を定義します。
  2. プロダクトを含む API プロダクト バンドルを作成します。API プロダクト バンドルを作成するをご覧ください。
    API プロダクト バンドルのトランザクション記録ポリシーに、料金プランの定義に使用するカスタム属性を追加します。詳細については、このトピックの概要とトランザクション記録ポリシーの作成をご覧ください。
  3. API プロダクト バンドルの料金プランを作成し、カスタム評価パラメータを指定します。

詳しくは、管理画面を使用して料金表プランの詳細を設定するをご覧ください。

従来の Edge(Private Cloud)

Classic Edge UI を使用してカスタム属性プラン付きのレート表を作成するには、次の手順を行います。

  1. API プロダクトのトランザクション記録ポリシーで、料金プランの定義に使用するカスタム属性を追加します。詳細については、このトピックの概要とトランザクション記録ポリシーを作成するをご覧ください。これは、API パッケージに含める API プロダクトごとに行います。
  2. API プロダクトとトランザクション記録ポリシーを必要に応じて構成したら、プロダクトを含む API パッケージを作成します。API パッケージを作成するをご覧ください。
  3. API パッケージの料金プランを作成し、料金プランの種類として [カスタム属性を使用したレート表] を選択します。
  4. [レート表] リンクをクリックします。[レート表] ウィンドウが開きます。

  5. [カスタム属性] プルダウン メニューからカスタム属性を選択します。メニューには、トランザクション記録ポリシーでプロダクトのカスタム属性がリスト表示されます。各トランザクション内では、選択したカスタム属性の値に基づいて、デベロッパーに料金が請求されます。
    (属性値 × レート = デベロッパーへの請求)
  6. 必要に応じて、料金表プランの詳細を指定するの説明に沿ってフリーミアム プランを設定します。
  7. 料金表プランの詳細を指定するの説明に沿って、課金モデルを設定します。ただし、カスタム属性の料金プランタイプの料金表では、課金モデルは選択したカスタム属性に基づきます。たとえば、課金モデルとして定額料金を選択した場合、デベロッパーはトランザクションごとの固定料金ではなく、各トランザクションで送信されたバイト数などのカスタム属性に基づいて固定料金が請求されます。詳しくは、計算をご覧ください。
  8. [下書きを保存] をクリックします。
    プランを公開できるのは、最終的な決定が不可欠な場合のみです。公開日の設定とプランの公開については、料金プランを公開するをご覧ください。

詳しくは、 UI を使用して料金表プランの詳細を指定するをご覧ください。

UI を使用してカスタム属性で調整可能な通知プランを構成する

以下で説明するように、カスタム属性を使用して調整可能な通知プランを構成します。

Edge

Edge UI を使用してカスタム属性で料金表プランを構成するには:

  1. API プロダクトを追加するときにカスタム属性を定義します。
  2. プロダクトを含む API プロダクト バンドルを作成します。API プロダクト バンドルを作成するをご覧ください。
    API プロダクト バンドルのトランザクション記録ポリシーに、料金プランの定義に使用するカスタム属性を追加します。詳細については、このトピックの概要とトランザクション記録ポリシーの作成をご覧ください。
  3. API プロダクト バンドルの料金プランを作成し、カスタム評価パラメータを指定します。

詳細については、UI を使用して調整可能な通知プランを構成するをご覧ください。

従来の Edge(Private Cloud)

Classic Edge UI を使用してカスタム属性で料金表プランを構成するには:

  1. API プロダクトのトランザクション記録ポリシーで、料金プランの定義に使用するカスタム属性を追加します。詳細については、このトピックの概要とトランザクション記録ポリシーを作成するをご覧ください。これは、API パッケージに含める API プロダクトごとに行います。
  2. API プロダクトとトランザクション記録ポリシーを必要に応じて構成したら、プロダクトを含む API パッケージを作成します。API パッケージを作成するをご覧ください。
  3. API パッケージの料金プランを作成し、料金プランのタイプとして [Adjustable Notification with Custom Attribute] を選択します。
  4. [詳細] リンクをクリックします。調整可能な通知ウィンドウが開きます。

  5. [カスタム属性] プルダウン メニューでカスタム属性を選択します。メニューには、トランザクション記録ポリシーでプロダクトのカスタム属性がリストされます。デベロッパーの合計トランザクション数は、各トランザクション内で選択したカスタム属性の値に基づいて計算されます。
  6. [集計ベース] を、トランザクションの量を集計する期間に設定します。1 ~ 24 か月の数値を選択してください。この値はデフォルトで 1 か月に設定されます。
  7. [Apply and Close] をクリックします。
  8. [下書きを保存] をクリックします。
    プランを公開できるのは、最終的な決定が不可欠な場合のみです。公開日の設定とプランの公開については、料金プランを公開するをご覧ください。

詳しくは、 UI を使用して調整可能な通知プランの詳細を指定するをご覧ください。

API を使用してカスタム属性を含む料金プランの詳細を指定する

前提条件となる次の手順を実施します。

  1. API プロダクトのトランザクション記録ポリシーで、料金プランの定義に使用するカスタム属性を追加します。詳細については、このトピックの概要とトランザクション記録ポリシーを作成するをご覧ください。これは、API パッケージに含める API プロダクトごとに行います。
  2. API プロダクトとトランザクション記録ポリシーを必要に応じて構成したら、プロダクトを含む API パッケージを作成します。API パッケージを作成するをご覧ください。

次に、API を使用して料金プランを作成します。

料金プランの作成時に、カスタム属性を使用して料金プランの詳細を指定します。詳細は、/organizations/{org_name}/monetization-packages/{package_id}/rate-plans の呼び出しのリクエスト本文内の ratePlanDetails プロパティで指定します。詳細で、カスタム属性の名前を識別する評価パラメータ値を指定します。また、指定した時間間隔でカスタム属性を集約する評価パラメータ値を指定することもできます。

料金プランの詳細オプションの一覧については、料金プランの詳細の構成設定をご覧ください。

たとえば、以下では、messageSize という名前のカスタム属性に基づいて、カスタム属性プランを含むレート表を作成します(太字の項目を参照)。

$ curl -H "Content-Type:application/json" -X POST -d \
'{
   "name": "Custom attribute-based rate card plan",
   "developer":null,
   "developerCategory":null,
   "currency": {
     "id" : "usd"
     },     
   "description": "Custom attribute-based rate card plan",
   "displayName" : "Custom attribute-based rate card plan",
   "frequencyDuration": "1",
   "frequencyDurationType": "MONTH",
   "earlyTerminationFee": "10",
   "monetizationPackage": {
      "id": "location"
        },
      "organization": {
       "id": "{org_name}"
      },    
   "paymentDueDays": "30",
   "prorate": "false",
   "published": "false",     
   "ratePlanDetails":[
      {
        "currency":{
           "id":"usd"
        },
      "duration":1,
      "durationType":"MONTH",
      "meteringType":"VOLUME",
      "paymentDueDays":"30",
      "ratingParameter":"messageSize",
      "ratingParameterUnit":"MB",
      "organization":{
         "id":"{org_name}"
      },
      "ratePlanRates":[
         {
           "rate":0.15,
           "startUnit":0,
           "type":"RATECARD",
           "endUnit":1000
         },
         {
           "rate":0.1,
           "startUnit":1000,
           "type":"RATECARD",
           "endUnit":null
         }
      ],
      "freemiumUnit":0,
      "freemiumDuration":0,
      "freemiumDurationType":"MONTH",
      "type":"RATECARD",
      "customPaymentTerm":false
      }
    ],
    "freemiumUnit":0,
    "freemiumDuration":0,
    "freemiumDurationType":"MONTH",
    "contractDuration":"1",
    "contractDurationType":"YEAR", 
    "recurringStartUnit": 1,
    "recurringType": "CALENDAR",
    "recurringFee": "10",
    "setUpFee": "10",
    "startDate": "2013-09-15 00:00:00",
    "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans" \
-u email:password

以下では、messageSize という名前のカスタム属性に基づいて、カスタム属性を使用した Adjustable Notification の料金プランを作成します(太字の項目を参照)。

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "AdjustableNotification",
     "displayName": "Custom attribute-based adjustable notification plan",
     "description": "Custom attribute-based adjustable notification plan",
     "published": "true",  
     "organization": {
      "id": "myorg"
     },
     "startDate": "2016-04-15 00:00:00",
     "type": "STANDARD",
     "monetizationPackage": {
        "id": "p1",
        "name": "test"
     },
     "currency": {
        "id" : "usd",
        "name" : "USD"
     },
     "ratePlanDetails": [
        {
           "type": "USAGE_TARGET",
           "meteringType": "DEV_SPECIFIC",
           "duration": 1,
           "durationType": "MONTH",
           "ratingParameter": "messageSize",
           "ratingParameterUnit": "MB",
           "organization": {
             "id": "myorg"
           },
           "currency": {
             "id": "usd",
             "name": "USD"
           }
        }
     ]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/monetization-packages/p1/rate-plans"  \
-u email:password