トランザクション記録ポリシーを構成する

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

以降のセクションで説明するように、API プロダクト バンドル内の各 API プロダクトにトランザクション記録ポリシーを構成します。

はじめに

トランザクション記録ポリシーを使用すると、収益化でトランザクション パラメータとカスタム属性をキャプチャできます。収益化では、料金プランの適用などの収益化処理を実行するためにこの情報が必要です。

たとえば、収益分配の料金プランを設定した場合、収益化対象の API プロダクトに関する各トランザクションから得られた収益の割合は、リクエストを発行したアプリのデベロッパーと共有されます。収益分配率は、トランザクションの正味価格または総価格(どちらになるかは指定)に基づきます。つまり、各トランザクションの総価格または正味価格の割合に基づいて収益分配が決定されます。このため、収益化では取引の総額または正味価格を知る必要があります(該当する場合)。トランザクション記録ポリシーで行った設定から、総額または正味価格が取得されます。

トランザクションごとにデベロッパーに請求する料金表プランを設定する場合は、トランザクションで送信されたバイト数などのカスタム属性に基づいてプランの料金を設定できます。収益化部門は、カスタム属性の内容とそれがどこにあるかを把握する必要があります。そのため、トランザクション記録ポリシーでカスタム属性を指定する必要があります。

トランザクション記録ポリシーでトランザクション属性を指定するだけでなく、トランザクション成功基準を指定して、トランザクションが成功したかどうかを判断することもできます(請求目的)。トランザクションの成功基準の設定例については、トランザクション記録ポリシーでのトランザクション成功基準の設定例をご覧ください。また、API プロダクトのカスタム属性(基本料金プランで課金される)を指定することもできます。

トランザクション記録ポリシーの構成

次の手順で [Product Bundles] ページにアクセスします。

エッジ

Edge UI を使用して API プロダクト バンドルを追加する場合は、次の手順でトランザクション記録ポリシーを構成する必要があります。

  1. [Transaction Recording Policy] セクションで、設定する API プロダクトを選択します(プロダクト バンドルに複数の API プロダクトがある場合)。
  2. トランザクション属性を構成します
  3. カスタム属性を構成します
  4. 一意のトランザクション ID を使用してリソースをリンクする
  5. 払い戻しを設定します。
  6. API プロダクト バンドルで定義されている API プロダクトごとに、この手順を繰り返します。

従来の Edge(Private Cloud)

Classic Edge UI を使用してトランザクション記録ポリシーを構成するには:

  1. http://ms-ip:9000 にログインします。ここで、ms-ip は Management Server ノードの IP アドレスまたは DNS 名です。
  2. 上部のナビゲーション バーで [Publish] > [Products] を選択します。
  3. 該当する API プロダクトの行で、[+ Transaction Recording Policy] をクリックします。[New Transaction Recording Policy] ウィンドウが表示されます。
  4. 次の手順でトランザクション記録ポリシーを構成します。
  5. [保存] をクリックします。

トランザクション属性の構成

[Transaction Attributes] セクションで、収益化トランザクションの成功を示す条件を指定します。

  1. [Transaction Success Criteria] フィールドで、Status 属性の値に基づいて式(後述)を指定し、トランザクションが成功したかどうかを判断するための(請求目的に)使用します。失敗した(式の条件を満たしていない)トランザクションは記録されますが、料金プランは適用されません。次に例を示します。

    txProviderStatus == 'OK'

  2. Status 属性には、[Transaction Success Criteria] フィールドに設定されている式で使用される値が含まれます。次のフィールドを定義して [Status] 属性を構成します。
    項目 説明
    API リソース API プロダクトで定義される URI パターン。収益化対象のトランザクションの識別に使用されます。
    回答の地域 属性が指定されているレスポンスの場所。有効な値は、フロー変数、ヘッダー、JSON 本文、XML 本文です。
    レスポンスの値。複数の値を指定するには、[+ x を追加x](例: [+ フロー変数を追加])をクリックします。
  3. オプションのトランザクション属性を構成するには、[Use Optional Attributes] 切り替えを有効にして、次の表で定義されているトランザクション属性を構成します。
    属性 説明
    総額

    この属性は、収益分配モデルを使用する料金プランにのみ適用されます。 これらの料金プランでは、総価格または正味価格のいずれかが必須です。数値が文字列型で表されていることを確認してください。トランザクションの総額。収益分配プランでは、総価格属性または正味価格属性のいずれかを記録する必要があります。必要な属性は、収益分配率によって異なります。たとえば、トランザクションの総額に基づく収益分配率のプランを設定できます。その場合、総価格フィールドは必須です。

    平均費用

    この属性は、収益分配モデルを使用する料金プランにのみ適用されます。 これらの料金プランでは、総価格または正味価格のいずれかが必須です。数値が文字列型で表されていることを確認してください。取引の正味価格。収益分配プランの場合は、正味価格フィールドまたは総価格フィールドのいずれかを記録する必要があります。必要なフィールドは、収益分配によって異なります。たとえば、トランザクションの正味価格に基づく収益分配料金プランを設定できます。その場合、[正味価格] フィールドは必須です。

    通貨

    この属性は、収益分配モデルを使用する料金プランに必要です。 取引に適用される通貨の種類。

    エラーコード

    取引に関連付けられたエラーコード。失敗したトランザクションに関する詳細情報を提供します。

    アイテムの説明

    取引の説明。

    この属性は、収益分配モデルにのみ関連し、API 呼び出しで税額を取得する場合に限られます。数値が文字列型で表されていることを確認してください。購入に対する税額。正味価格 + 税金 = 総額。

たとえば、次の値を設定することで、Monetization は response.reason.phrase という変数のメッセージ レスポンスからフロー変数の値を取得します。値が OK で、Monetization Limits Check ポリシーが API プロキシ ProxyEndpoint リクエストに接続されている場合、Monetization はそれをトランザクションとしてカウントします。

項目
トランザクションの成功基準 txProviderStatus == 'OK'
ステータス: API リソース **
ステータス: 回答の位置情報 フロー変数
ステータス: フロー変数 response.reason.phrase

カスタム属性の構成

[Custom Attributes] セクションで、トランザクション記録ポリシーに含めるカスタム属性を指定します。たとえば、料金表を設定し、トランザクションごとにデベロッパーに請求する場合は、トランザクションで送信されたバイト数などのカスタム属性に基づいてプランの料金を設定できます。次に、そのカスタム属性をトランザクション記録ポリシーに含める必要があります。

これらの各属性はトランザクション ログに格納され、トランザクション ログに対してクエリを実行できます。これらは料金プランの作成時にも表示されます(これにより、プランの料金の基準となるこれらの属性を 1 つ以上選択できます)。

トランザクション記録ポリシーで定義されたカスタム属性を収益概要レポートに追加できます。詳しくは収益概要レポートにカスタム トランザクション属性を含めるをご覧ください。

カスタム属性を構成するには、[カスタム属性の使用] をオンに切り替えて、最大 10 個のカスタム属性を定義します。トランザクション記録ポリシーに含めるカスタム属性ごとに、次の情報を指定する必要があります。

項目 説明
カスタム属性名 カスタム属性を説明する名前を入力します。料金プランがカスタム属性に基づいている場合、この名前が料金プランの詳細に表示されます。たとえば、カスタム属性で期間をキャプチャする場合は、属性に duration という名前を付けます。カスタム属性の実際の単位(時間、分、秒など)は、カスタム属性の料金プランを作成するときに、評価単位フィールドに設定されます(カスタム属性の詳細で料金プランを指定するをご覧ください)。
API リソース トランザクションでアクセスされる API リソースの URI サフィックス(ベースパスに続く URI フラグメント)を 1 つ以上選択します。使用できるリソースは、transaction 属性の場合と同じです。
回答の地域 レスポンス内の、属性が指定されているロケーションを選択します。有効な値は、フロー変数、ヘッダー、JSON 本文、XML 本文です。
カスタム属性の値を指定します。指定する各値は、指定した場所のカスタム属性を提供するフィールド、パラメータ、またはコンテンツ要素に対応しています。複数の値を指定するには、[+ x を追加x](例: [+ フロー変数を追加])をクリックします。

たとえば、Content Length という名前のカスタム属性を構成し、レスポンスの場所として Header を選択した場合、Content Length の値が HTTP Content-Length フィールドで指定されている場合は、値として Content-Length を指定します。

トランザクションの中には、1 つのリソースに対して API 呼び出しを行うだけのシンプルなものもあります。ただし、他のトランザクションはより複雑になる場合があります。たとえば、モバイルゲーム アプリでアプリ内アイテムを購入するためのトランザクションに、次のように複数のリソース呼び出しが含まれているとします。

  • プリペイド ユーザーが商品を購入するのに十分なクレジットがあることを確認し、購入資金を割り当て(「予約」)する予約 API の呼び出し。
  • プリペイド ユーザーの口座から資金を減額する Charge API の呼び出し。

トランザクション全体を処理するには、収益化に最初のリソース(Reserve API に対する呼び出しとレスポンス)と 2 番目のリソース(charge API からの呼び出しとレスポンス)をリンクする方法が必要です。これは、「一意のトランザクション ID でリソースをリンク」セクションで指定した情報に依存します。

カスタム属性を構成するには、[一意のトランザクション ID を使用する] 切り替えを有効にして、トランザクションをリンクします。トランザクションごとに、リソース、レスポンスのロケーション、他のトランザクションの対応する値にリンクされている属性値を指定します。

たとえば、Reservation API 呼び出しと charge API 呼び出しが次のようにリンクしているとします。Reserve API からのレスポンス ヘッダーの session_id というフィールドが、charge API から reference_id というレスポンス ヘッダーに対応しているとします。この場合、[Link Resources with Unique Transaction ID] セクションのエントリを次のように設定できます。

リソース 回答の地域
reserve/{id}**

ヘッダー

session_id
/charge/{id}**

ヘッダー

reference_id

払い戻しの設定

[払い戻し] セクションでは、収益化で払い戻しの処理に使用する属性を指定します。

たとえば、収益化対象の API を使用するモバイルアプリからユーザーがアイテムを購入したとします。トランザクションは、共有の収益プランに基づいて収益化されます。しかし、お客様が商品に満足せず、返品を希望しているとします。払い戻しを行う API 呼び出しを使用してアイテムの払い戻しを行う場合は、収益化によって必要な収益化の調整が行われます。これは、トランザクション記録ポリシーの [Refunds] セクションで指定した情報に基づいて行われます。

払い戻しを設定するには、[Use Refund Attributes] 切り替えを有効にして、払い戻しの詳細を定義します。

  1. 次のフィールドを定義して払い戻し条件を定義します。
    項目 説明
    回答の地域 払い戻しトランザクションのリソース。API プロダクトで複数のリソースが提供される場合は、払い戻しを行うリソースのみを選択できます。
    払い戻しの成功基準 払い戻しトランザクションが成功したかどうかを判別するための、ステータス 属性の値に基づく式(後述)。失敗した(式の条件を満たしていない)払い戻しトランザクションは記録されますが、料金プランは適用されません。次に例を示します。

    txProviderStatus == 'OK'

  2. 次のフィールドを定義して [Status] 属性を構成します。
    項目 説明
    回答の地域 属性が指定されているレスポンスの場所。有効な値は、フロー変数、ヘッダー、JSON 本文、XML 本文です。
    レスポンスの値。複数の値を指定するには、[+ x を追加x](例: [+ フロー変数を追加])をクリックします。
  3. 次のフィールドを定義して、[Parent ID] 属性を構成します。
    項目 説明
    回答の地域 属性が指定されているレスポンスの場所。有効な値は、フロー変数、ヘッダー、JSON 本文、XML 本文です。
    払い戻しが処理されるトランザクションの ID。たとえば、ユーザーが商品を購入して払い戻しをリクエストした場合、親取引 ID はその購入取引の ID です。複数の値を指定するには、[+ x を追加x](例: [+ フロー変数を追加])をクリックします。
  4. オプションの払い戻し属性を設定するには、[Use Optional Refund Attributes] 切り替えを有効にして、属性を構成します。オプションの refund 属性は、トランザクション属性の設定で定義されているオプションのトランザクション属性と同じです。

API を使用したトランザクション記録ポリシーの管理

以降のセクションでは、API を使用してトランザクション記録ポリシーを管理する方法について説明します。

API を使用したトランザクション記録ポリシーの作成

トランザクション記録ポリシーは、API プロダクトの属性として指定します。この属性の値は、以下を識別します。

  • トランザクション記録ポリシーが接続されている商品リソースの URI サフィックス。サフィックスには、中かっこで囲まれたパターン変数が含まれます。パターン変数は、実行時に API サービスによって評価されます。たとえば、次の URI サフィックスにはパターン変数 {id} が含まれています。
    /reserve/{id}**
    

    この場合、API サービスはリソースの URI サフィックスを /reserve として評価し、その後に API プロバイダが定義した ID で始まるサブディレクトリを続けます。

  • レスポンスに添付されたリソース。1 つの API プロダクトに複数のリソースを含めることができ、各リソースには、そのリソースからのレスポンスにトランザクション記録ポリシーを関連付けることができます。
  • 変数抽出ポリシー。トランザクション記録ポリシーがキャプチャするトランザクション パラメータのレスポンス メッセージからコンテンツを抽出できるようにします。

トランザクション記録ポリシー属性を API プロダクトに追加するには、PUT リクエストを(Monetization API ではなく)管理 API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} に送信します。

API を使用してトランザクションの成功基準を指定する

トランザクションが成功したかどうかを判断するためのトランザクション成功基準を指定できます(請求目的)。失敗したトランザクション(式の条件を満たすトランザクション)は記録されますが、料金プランは適用されません。トランザクションの成功基準の設定例については、トランザクション記録ポリシーでのトランザクション成功基準の設定例をご覧ください。

トランザクションの成功基準を API プロダクトの属性として指定します。そのためには、PUT リクエストを(Monetization API ではなく)管理 API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} に発行します。

たとえば、次のリクエストでは、txProviderStatus の値が success の場合、トランザクションは成功です(トランザクションの成功基準に関連する仕様がハイライト表示されています)。

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
        "apiResources": [
        "/reserve/{id}**"       
        ],
        "approvalType": "auto",
        "attributes": [                         
        {
                "name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
                "value": "txProviderStatus == 'OK'"
        }
        ],
        "description": "Payment",
        "displayName": "Payment",
        "environments": [
        "dev"
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
        ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

API を使用したカスタム属性の指定

基本料金プランで課金される API プロダクトのカスタム属性を指定できます。たとえば、トランザクションごとにデベロッパーに請求する料金表プランを設定する場合、トランザクションで送信されたバイト数などのカスタム属性に基づいて、プランの料金を設定できます。料金プランを作成する際に、プランの料金の基準となるカスタム属性を 1 つ以上指定できます。ただし、料金プラン内の特定の商品には、プランの料金を基準とするカスタム属性を 1 つだけ設定できます。

カスタム属性は、API プロダクトの属性として指定します。そのためには、PUT リクエストを(Monetization API ではなく)管理 API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} に発行します。

API プロダクトに追加するカスタム属性ごとに、名前と属性値を指定する必要があります。名前は MINT_CUSTOM_ATTRIBUTE_{num} の形式にする必要があります({num} は整数)。

たとえば、次のリクエストでは 3 つのカスタム属性を指定しています。

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
        "apiResources": [
        "/reserve/{id}**",
        "/charge/{id}**"
        ],
        "approvalType": "auto",
        "attributes": [
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_1",
                "value": "test1"
        },
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_2",
                "value": "test2"
        }
 
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
                ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

トランザクション記録ポリシーでのトランザクション成功基準の設定例

次の表に、トランザクションの成功条件の式と、API プロキシから返される txProviderStatus の値に基づいて、成功したトランザクションと失敗したトランザクションの例を示します。txProviderStatus は、収益化がトランザクションの成功を判断するために使用する内部変数です。

成功基準の式 有効な式 API プロキシの txProviderStatus 値 評価結果
null true "200" false
"" false "200" false
" " false "200" false
"sdfsdfsdf" false "200" false
"txProviderStatus =='100'" true "200" false
"txProviderStatus =='200'" true "200" true
"true" true "200" true
"txProviderStatus=='OK' OR
txProviderStatus=='Not Found' OR
txProviderStatus=='Bad Request'"
true "OK" true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'" true "OK" true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'" true "Not Found" true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'" true "Bad Request" true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'" true "Bad Request" true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'" true null false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" true "bad request" true
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" true "Redirect" false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" true "heeeelllooo" false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'" true null false
"txProviderStatus == 100" true "200" false