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

現在、Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントに移動 情報

はじめに

場合によっては、取引カウンタを変数またはカスタム値に基づくようにする必要があります。たとえば、次のことを行う必要があります。

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

カスタム属性を含む料金プランを使用すると、API 呼び出しのメッセージ内の値を識別できます。この値はカウンタとして機能し、取引数と請求額の計算に使用されます。

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

• カスタム属性を含む料金カード
• カスタム属性による調整可能な通知

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

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

カスタム属性の値が料金プランの取引数と請求額にどのように反映されるかは、次の表に示すように課金モデルによって異なります。

充電モデル	カスタム属性の計算
定額と使用量に基づくバンド	custom attribute number * rate = charge to developer 定額料金の場合、カスタム属性番号は、レートに掛けられる取引数になります。ボリューム バンドルの場合、バンドルのトランザクション数はカスタム属性の数だけ増加し、そのトランザクション数に基づいてデベロッパーに課金されます。たとえば、メッセージ内のカスタム属性の値が 10 の場合、デベロッパーは 10 件の取引に対して課金され、現在のバンド数に 10 件の取引が追加されます。デベロッパーが現在のバンドで残りの取引が 6 件しかない場合、6 にそのバンドのレートが掛けられます。残りの 4 は次のバンドに移動し、そのバンドのレートと掛けられます。 ボリューム バンド制プランで、最後のボリューム バンドに上限があり（「無制限」ではない）、トランザクションが上限を超えると、次の 2 つの処理が行われます。 デベロッパーは「超過」額を無料で受け取ります。 プランの期間がリセットされるまで、デベロッパー アプリは API の呼び出しをブロックされます。 プランがリセットされるタイミングについて詳しくは、定期的な料金の請求とバンドルプランのリセットはいつ行われますか？をご覧ください。
バンドル	バンドルはトランザクションではなくグループ単位で課金されるため、次の計算が行われます。 custom attribute number = amount added to bundle count たとえば、メッセージのカスタム属性番号が 10 の場合、バンドルで使用される取引数に 10 が追加されます。現在のバンドルに残りのトランザクションが 6 つしかない場合、そのバンドルは満たされ、次のバンドル数は 4 ずつ増加します。次のバンドルのレート（ある場合）が課金されます。 最後のバンドルに上限があり（「無制限ではない」）、トランザクションがその上限を超えると、次の 2 つの状況が発生します。 デベロッパーは「超過」額を無料で受け取ります。 プランの期間がリセットされるまで、デベロッパー アプリは API の呼び出しをブロックされます。 プランがリセットされるタイミングについて詳しくは、定期的な料金の請求とバンドルプランのリセットはいつ行われますか？をご覧ください。
調整可能な通知	調整可能な通知の場合、次のように計算されます。 custom attribute number = amount added to transaction count たとえば、メッセージ内のカスタム属性番号が 10 の場合、トランザクションの合計数に 10 が追加されます。

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

Transaction Recording ポリシー（API プロダクト バンドル上）は、メッセージ内でカスタム属性値を検索する場所を収益化に指示します。カスタム属性は、API プロダクト バンドルの Transaction Recording ポリシーの [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>

料金プランの設定

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

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

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

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 という名前のカスタム属性に基づいて、カスタム属性付きの調整可能な通知の料金プランを作成します（太字の項目を参照）。

$ 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