このページは Cloud Translation API によって翻訳されました。

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

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

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

はじめに

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

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

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

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

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

次の手順に沿って [一括販売] ページにアクセスします。

エッジ

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

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

Classic Edge（Private Cloud）

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

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

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

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

[Transaction Success Criteria] フィールドで、ステータス属性の値（後述）に基づいて式を指定します。この式は、トランザクションが成功するタイミング（請求目的）を判断します。失敗した（つまり、式の条件を満たしていない）トランザクションは記録されますが、料金プランは適用されません。次に例を示します。
txProviderStatus == 'OK'

txProviderStatus は、収益化がトランザクションの成功を判定するために使用する内部変数です。トランザクションの成功基準の設定例については、トランザクション記録ポリシーでのトランザクション成功条件の設定例をご覧ください。

Status 属性には、[Transaction Success Criteria] フィールドで構成された式で使用される値が含まれます。次のフィールドを定義して、[ステータス] 属性を構成します。

項目	説明
API リソース	API プロダクトで定義される URI パターン。収益化トランザクションの識別に使用されます。収益化に関する注意: トランザクション記録ポリシーを定義するために使用される API プロダクトのリソースパスには、`/` を明示的に使用します。収益化では、`/` はベースパスのみとして扱い、`/` は扱いません。API プロダクトを管理するをご覧ください。
レスポンスの場所	属性が指定されているレスポンスの場所。有効な値は、フロー変数、ヘッダー、JSON 本文、XML 本文です。
値	レスポンスの値です。複数の値を指定するには、[+ x を追加]（例: [+ フロー変数を追加]）をクリックします。

オプションのトランザクション属性を構成するには、[Use Optional Attributes] を切り替え、次の表で定義されているトランザクション属性を構成します。

属性	説明
総額	この属性は、収益分配モデルを使用する料金プランにのみ適用されます。これらの料金プランでは、総価格または純価格のいずれかが必須です。数値が文字列型で表されていることを確認してください。1 回の取引の総額。収益分配プランの場合は、総価格属性または正味価格属性のいずれかを記録する必要があります。必要な属性は、収益分配率によって決まります。たとえば、トランザクションの総額に基づく収益分配率のプランを設定できます。その場合、[総価格] フィールドは必須です。
平均費用	この属性は、収益分配モデルを使用する料金プランにのみ適用されます。これらの料金プランでは、総価格または純価格のいずれかが必須です。数値が文字列型で表されていることを確認してください。取引の正味価格。収益分配プランの場合は、純価格フィールドまたは総価格フィールドのいずれかを記録する必要があります。どのフィールドが必須かは、収益分配率によって決まります。たとえば、トランザクションの正味価格に基づく収益分配率のプランを設定できます。その場合、[ネット価格] フィールドは必須です。
通貨	この属性は、収益分配モデルを使用する料金プランに必要です。取引に適用される通貨の種類。
エラーコード	トランザクションに関連するエラーコード。失敗したトランザクションに関する詳細情報を提供します。
アイテムの説明	取引の説明。
税	この属性は、API 呼び出しで税額を取得する場合にのみ、収益分配モデルにのみ適用されます。数値が文字列型で表現されていることを確認してください。購入に対する税額。正味価格 + 税金 = 総額

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

項目	値
トランザクションの成功基準	`txProviderStatus == 'OK'`
ステータス: API リソース	`**`
ステータス: レスポンスの場所	フロー変数
ステータス: フロー変数	`response.reason.phrase`

カスタム属性の構成

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

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

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

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

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

一意のトランザクション ID を使用してリソースをリンクする

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

Reserve API の呼び出し。プリペイドユーザーが商品を購入するのに十分なクレジットを確保し、購入資金を割り当てる（「予約」）。
プリペイドユーザーのアカウントから残高を減額する Charge API の呼び出し。

トランザクション全体を処理するには、収益化に最初のリソース（Reservation API の呼び出しとレスポンス）と 2 番目のリソース（charge API の呼び出しとレスポンス）をリンクする方法が必要です。これを行うには、[一意のトランザクション ID でリソースをリンク] セクションで指定した情報を使用します。

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

たとえば、Reserve 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 呼び出しを使用してアイテムの払い戻しが行われた場合は、収益化によって必要な収益化の調整が行われます。この処理は、トランザクション記録ポリシーの [払い戻し] セクションで指定した情報に基づいて行われます。

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

次のフィールドを定義して払い戻し条件を定義します。

項目	説明
レスポンスの場所	払い戻しトランザクションのリソース。API プロダクトで複数のリソースが提供される場合は、払い戻しを行うリソースのみを選択できます。
払い戻しの成功基準	払い戻しトランザクションが成功するタイミングを判断するための（請求目的で）Status 属性の値に基づく式（後述）。失敗した払い戻しトランザクション（つまり、式の条件を満たしていない）は記録されますが、料金プランは適用されません。次に例を示します。 `txProviderStatus == 'OK'`

次のフィールドを定義して、[ステータス] 属性を構成します。

項目	説明
レスポンスの場所	属性が指定されているレスポンスの場所。有効な値は、フロー変数、ヘッダー、JSON 本文、XML 本文です。
値	レスポンスの値です。複数の値を指定するには、[+ x を追加]（例: [+ フロー変数を追加]）をクリックします。

次のフィールドを定義して、Parent ID 属性を構成します。

項目	説明
レスポンスの場所	属性が指定されているレスポンスの場所。有効な値は、フロー変数、ヘッダー、JSON 本文、XML 本文です。
値	払い戻しが処理される取引の ID。たとえば、ユーザーが商品を購入した後に払い戻しをリクエストした場合、親取引 ID は購入取引の ID になります。複数の値を指定するには、[+ x を追加]（例: [+ フロー変数を追加]）をクリックします。

オプションの払い戻し属性を設定するには、[Use Optional Refund Attributes] 切り替えを有効にして、属性を設定します。オプションの払い戻し属性は、トランザクション属性の構成で定義されているオプションのトランザクション属性と同じです。
注: 属性値が String 型で表現されていることを確認してください。そうしないと、トランザクションがカウントされない場合があります。

API を使用してトランザクション記録ポリシーを管理する

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

API を使用してトランザクション記録ポリシーを作成する

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

トランザクション記録ポリシーが接続されている商品リソースの URI サフィックス。サフィックスには、中かっこで囲まれたパターン変数が含まれます。パターン変数は、実行時に API サービスによって評価されます。たとえば、次の URI サフィックスには、パターン変数 {id} が含まれています。
```
/reserve/{id}**
```
この場合、API Services はリソースの URI サフィックスを /reserve として評価し、その後に API プロバイダによって定義された ID で始まるサブディレクトリが続きます。
接続先のレスポンスのリソース。1 つの API プロダクトに複数のリソースを含めることができ、各リソースには、そのリソースからのレスポンスに 1 つのトランザクション記録ポリシーを関連付けることができます。
変数抽出ポリシー。トランザクション記録ポリシーがキャプチャするトランザクションパラメータのレスポンスメッセージからコンテンツを抽出できるようにします。

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

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

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

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

たとえば、次のリクエストでは、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 プロダクトの属性として指定します。これを行うには、（収益化 API ではなく）管理 API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} に PUT リクエストを発行します。

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