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

現在、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 が追加されます。

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

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 を使用して、カスタム属性で料金表プランを構成します。

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