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

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

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

はじめに

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

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

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

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

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

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

トランザクション属性を構成する

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

1. [Transaction Success Criteria] フィールドで、トランザクションが成功したと判断するタイミング（課金目的）を決定するための Status 属性（後述）の値に基づく式を指定します。成功しなかった取引（つまり、式内の条件を満たしていない取引）は記録されますが、料金プランは適用されません。次に例を示します。

   txProviderStatus == 'OK'

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

   フィールド	説明
   API リソース	収益化されたトランザクションの識別に使用される API プロダクトで定義された URI パターン。
   回答の場所	属性が指定されているレスポンスの場所。有効な値には、フロー変数、ヘッダー、JSON 本文、XML 本文があります。
   値	レスポンスの値。複数の値を指定するには、[+ x を追加]（[+ フロー変数] など）をクリックします。

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

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

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

カスタム属性の構成

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

これらの各属性はトランザクション ログに保存され、クエリできます。また、料金プランを作成するときにも表示されます（プランの料金の基準とする属性を 1 つ以上選択できるようにするため）。

トランザクション記録ポリシーで定義されたカスタム属性は、収益概要レポートにカスタム トランザクション属性を含めるで説明されているように、収益概要レポートに含めることができます。

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

一意のトランザクション ID を持つリソースをリンクする

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

• プリペイド ユーザーがプロダクトを購入するのに十分なクレジットを保有していることを確認し、購入用の資金を割り当てる（「確保する」）予約 API の呼び出し。
• 前払いユーザーのアカウントから資金を差し引く課金 API への呼び出し。

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

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

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

払い戻しを設定する

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

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

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

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

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

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

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

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

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

4. オプションの払い戻し属性を構成するには、[Use Optional Refund Attributes]（オプションの払い戻し属性を使用する）をオンに切り替えて、属性を構成します。省略可能な払い戻し属性は、トランザクション属性の構成で定義されている省略可能なトランザクション属性と同じです。

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

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

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

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

• トランザクション記録ポリシーが関連付けられているプロダクト リソースの URI 接尾辞。接尾辞には、中かっこで囲まれたパターン変数が含まれています。パターン変数は、ランタイム時に API サービスによって評価されます。たとえば、次の URI 接尾辞にはパターン変数 {id} が含まれています。

  /reserve/{id}**

  この場合、API Services は、リソースの URI 接尾辞を /reserve と、API プロバイダが定義した ID で始まるサブディレクトリとして評価します。

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

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

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

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

トランザクションの成功基準は、API プロダクトの属性として指定します。これを行うには、Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id}（収益化 API ではない）に 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 プロダクトの属性として指定します。これを行うには、Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id}（収益化 API ではない）に 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 は、収益化でトランザクションの成功を判断するために使用される内部変数です。