یک خط مشی ضبط تراکنش را پیکربندی کنید

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

همانطور که در بخش های زیر توضیح داده شده است، سیاست های ضبط تراکنش را برای هر محصول API در بسته محصول API خود پیکربندی کنید.

مقدمه

یک خط‌مشی ثبت تراکنش، کسب درآمد را قادر می‌سازد تا پارامترهای تراکنش و ویژگی‌های سفارشی را ثبت کند. کسب درآمد برای انجام پردازش درآمدزایی خود مانند اعمال طرح های نرخ به این اطلاعات نیاز دارد.

به عنوان مثال، اگر یک طرح نرخ سهم درآمد را تنظیم کنید، درصدی از درآمد حاصل از هر تراکنش مربوط به محصول API پولی شما با توسعه‌دهنده برنامه که درخواست را صادر می‌کند به اشتراک گذاشته می‌شود. سهم درآمد بر اساس قیمت خالص یا ناخالص معامله (شما مشخص می کنید کدام یک) است، یعنی درصدی از قیمت ناخالص یا خالص هر معامله برای تعیین سهم درآمد استفاده می شود. به همین دلیل، کسب درآمد باید قیمت ناخالص یا خالص یک تراکنش را بداند. قیمت ناخالص یا خالص را از تنظیماتی که در خط‌مشی ثبت تراکنش انجام می‌دهید دریافت می‌کند.

اگر یک طرح کارت نرخ راه‌اندازی می‌کنید، جایی که برای هر تراکنش از توسعه‌دهنده پول می‌گیرید، می‌توانید نرخ آن را بر اساس یک ویژگی سفارشی مانند تعداد بایت‌های ارسال شده در تراکنش تنظیم کنید. کسب درآمد باید بداند ویژگی سفارشی چیست و کجا آن را پیدا کند. بنابراین باید ویژگی سفارشی را در خط مشی ضبط تراکنش مشخص کنید.

علاوه بر مشخص کردن ویژگی‌های تراکنش در خط‌مشی ثبت تراکنش، می‌توانید معیارهای موفقیت تراکنش را برای تعیین زمان موفقیت آمیز تراکنش (برای اهداف شارژ) مشخص کنید. برای مثال هایی از تنظیم معیارهای موفقیت تراکنش، به نمونه هایی از تنظیم معیارهای موفقیت تراکنش در خط مشی ثبت تراکنش مراجعه کنید. همچنین می‌توانید ویژگی‌های سفارشی را برای یک محصول API تعیین کنید (که هزینه‌های طرح را بر اساس آن محاسبه می‌کنید).

پیکربندی خط مشی ضبط تراکنش

همانطور که در زیر توضیح داده شده است به صفحه Product Bundles دسترسی پیدا کنید.

پیکربندی ویژگی های تراکنش

در قسمت ویژگی های تراکنش ، معیارهایی را که نشان دهنده تراکنش موفقیت آمیز کسب درآمد است را مشخص کنید.

1. در قسمت معیارهای موفقیت تراکنش ، عبارتی را بر اساس مقدار ویژگی Status (در ادامه توضیح داده شده) برای تعیین زمان موفقیت آمیز بودن تراکنش (برای اهداف شارژ) مشخص کنید. معاملاتی که موفقیت آمیز نیستند (یعنی معیارهای بیان شده را ندارند) ثبت می شوند، اما برنامه های نرخ گذاری برای آنها اعمال نمی شود. به عنوان مثال:

   txProviderStatus == 'OK'

2. ویژگی Status حاوی مقدار مورد استفاده توسط عبارت پیکربندی شده در قسمت معیارهای موفقیت تراکنش است. ویژگی Status را با تعریف فیلدهای زیر پیکربندی کنید:

   میدان	توضیحات
   منبع API	الگوهای URI تعریف شده در محصول API که در شناسایی تراکنش های پولی استفاده می شود.
   محل پاسخگویی	محل پاسخ که در آن ویژگی مشخص شده است. مقادیر معتبر عبارتند از: متغیر جریان، سربرگ، JSON Body و XML Body.
   ارزش	ارزش پاسخ برای تعیین بیش از یک مقدار، روی + Add x (به عنوان مثال + Add Flow Variable ) کلیک کنید.

3. برای پیکربندی ویژگی های تراکنش اختیاری، کلید Use Optional Attributes را فعال کرده و هر یک از ویژگی های تراکنش تعریف شده در جدول زیر را پیکربندی کنید.

   صفت	توضیحات
   قیمت ناخالص	این ویژگی فقط برای طرح‌های نرخی که از مدل سهم درآمد استفاده می‌کنند، قابل استفاده است. برای آن طرح‌های نرخ، قیمت ناخالص یا قیمت خالص اجباری است. اطمینان حاصل کنید که مقدار عددی به عنوان یک نوع رشته بیان می شود. قیمت ناخالص برای یک معامله برای طرح های سهم درآمد، باید ویژگی قیمت ناخالص یا ویژگی قیمت خالص را ثبت کنید. اینکه کدام ویژگی مورد نیاز است بستگی به سهم درآمد دارد. به عنوان مثال، می توانید یک طرح نرخ سهم درآمد را تنظیم کنید که بر اساس قیمت ناخالص یک معامله است. در آن صورت، قسمت قیمت ناخالص الزامی است.
   قیمت خالص	این ویژگی فقط برای طرح‌های نرخی که از مدل سهم درآمد استفاده می‌کنند، قابل استفاده است. برای آن طرح‌های نرخ، قیمت ناخالص یا قیمت خالص اجباری است. اطمینان حاصل کنید که مقدار عددی به عنوان یک نوع رشته بیان می شود. قیمت خالص برای یک معامله برای طرح‌های سهم درآمد، باید فیلد قیمت خالص یا قیمت ناخالص را ثبت کنید. اینکه کدام قسمت مورد نیاز است بستگی به سهم درآمد دارد. به عنوان مثال، می توانید یک طرح نرخ سهم درآمد را تنظیم کنید که بر اساس قیمت خالص یک معامله است. در آن صورت، فیلد قیمت خالص الزامی است.
   ارز	این ویژگی برای طرح‌های نرخی که از مدل سهم درآمد استفاده می‌کنند لازم است. نوع ارزی که برای معامله اعمال می شود.
   کد خطا	کد خطا مرتبط با تراکنش. اطلاعات بیشتری درباره تراکنش ناموفق ارائه می دهد.
   توضیحات مورد	شرح معامله.
   مالیات	این ویژگی فقط برای مدل‌های اشتراک درآمد مرتبط است و تنها در صورتی که مبلغ مالیات در فراخوان‌های API ثبت شده باشد. اطمینان حاصل کنید که مقدار عددی به عنوان یک نوع رشته بیان می شود. مبلغ مالیات بر خرید قیمت خالص به اضافه مالیات = قیمت ناخالص.

به عنوان مثال، با تنظیم مقادیر زیر، کسب درآمد مقدار متغیر جریان را از پاسخ پیام در متغیری به نام response.reason.phrase دریافت می کند. اگر مقدار صحیح باشد و خط‌مشی بررسی محدودیت‌های کسب درآمد به درخواست پراکسی API ProxyEndpoint پیوست شده باشد، کسب درآمد آن را به عنوان یک تراکنش حساب می‌کند.

پیکربندی ویژگی های سفارشی

در بخش ویژگی‌های سفارشی ، ویژگی‌های سفارشی را شناسایی می‌کنید تا در خط‌مشی ضبط تراکنش لحاظ شوند. برای مثال، اگر یک طرح کارت نرخ راه‌اندازی کنید، جایی که برای هر تراکنش از توسعه‌دهنده هزینه دریافت می‌کنید، می‌توانید نرخ آن را بر اساس یک ویژگی سفارشی مانند تعداد بایت‌های ارسال شده در یک تراکنش تنظیم کنید. سپس باید آن ویژگی سفارشی را در خط مشی ضبط تراکنش قرار دهید.

هر یک از این ویژگی ها در گزارش تراکنش ذخیره می شوند که می توانید آن را پرس و جو کنید. آنها همچنین هنگام ایجاد یک برنامه نرخ نمایش داده می شوند (به طوری که می توانید یک یا چند مورد از این ویژگی ها را انتخاب کنید که بر اساس آن نرخ خود را برای طرح تعیین کنید).

می‌توانید ویژگی‌های سفارشی تعریف‌شده در خط‌مشی ثبت تراکنش را در گزارش‌های خلاصه درآمد خود بگنجانید، همانطور که در «شامل ویژگی‌های تراکنش سفارشی در گزارش‌های خلاصه درآمد» توضیح داده شده است.

برای پیکربندی ویژگی های سفارشی، ضامن Use Custom Attributes را فعال کرده و حداکثر 10 ویژگی سفارشی را تعریف کنید. برای هر ویژگی سفارشی که در خط مشی ضبط تراکنش درج می کنید، باید اطلاعات زیر را مشخص کنید.

منابع را با شناسه تراکنش منحصربفرد پیوند دهید

برخی از تراکنش ها ساده هستند و شامل یک فراخوانی API به یک منبع است. با این حال، سایر معاملات می توانند پیچیده تر باشند. به عنوان مثال، فرض کنید یک تراکنش برای خرید یک محصول درون برنامه ای در یک برنامه بازی موبایلی شامل چندین تماس با منبع است:

• تماس با یک API رزرو که تضمین می‌کند یک کاربر پیش‌پرداخت اعتبار کافی برای خرید محصول دارد و وجوه را برای خرید اختصاص می‌دهد ("رزرو").
• تماس با یک API شارژ که وجوه را از حساب کاربر پیش پرداخت کسر می کند.

برای پردازش کل تراکنش، کسب درآمد به روشی برای پیوند منبع اول (تماس و پاسخ به و از API رزرو) با منبع دوم (تماس و پاسخ به و از API شارژ) نیاز دارد. برای انجام این کار، به اطلاعاتی که در قسمت Link Resources with Unique Transaction ID مشخص می کنید، متکی است.

برای پیکربندی ویژگی‌های سفارشی، گزینه Use Unique Transaction IDs را فعال کنید و تراکنش‌ها را پیوند دهید. برای هر تراکنش، یک منبع، مکان پاسخ و مقدار مشخصه را مشخص می‌کنید که با مقادیر مربوطه در سایر تراکنش‌ها مرتبط است.

برای مثال، فرض کنید تماس API رزرو و تماس API شارژ به صورت زیر پیوند داده شده اند: فیلدی به نام session_id در سرصفحه پاسخ از API رزرو با سرصفحه پاسخی به نام reference_id از API شارژ مطابقت دارد. در این مورد، می توانید ورودی های قسمت Link Resources with Unique Transaction ID را به صورت زیر تنظیم کنید:

پیکربندی بازپرداخت

در بخش بازپرداخت ، ویژگی‌هایی را مشخص می‌کنید که کسب درآمد برای پردازش بازپرداخت استفاده می‌کند.

به عنوان مثال، فرض کنید یک کاربر محصولی را از یک برنامه تلفن همراه خریداری می کند که از API های کسب درآمد شما استفاده می کند. این تراکنش بر اساس طرح درآمد مشترک کسب درآمد می شود. با این حال، فرض کنید کاربر از محصول ناراضی است و می خواهد آن را برگرداند. اگر محصول با استفاده از تماس با API شما که بازپرداخت را انجام می دهد بازپرداخت شود، کسب درآمد تنظیمات لازم برای کسب درآمد را انجام می دهد. این کار را بر اساس اطلاعاتی که در بخش بازپرداخت خط مشی ضبط تراکنش مشخص کرده اید، انجام می دهد.

برای پیکربندی بازپرداخت، گزینه Use Refund Attributes را فعال کنید و جزئیات بازپرداخت را تعریف کنید:

1. معیارهای بازپرداخت را با تعریف فیلدهای زیر تعریف کنید:

   میدان	توضیحات
   محل پاسخگویی	منبع برای تراکنش بازپرداخت اگر محصول API منابع متعددی را ارائه می‌کند، می‌توانید تنها منبعی را انتخاب کنید که بازپرداخت را انجام می‌دهد.
   معیارهای موفقیت بازپرداخت	بیان بر اساس مقدار ویژگی Status (توضیح بعدی) برای تعیین زمان موفقیت آمیز بودن تراکنش بازپرداخت (برای اهداف شارژ). تراکنش‌های بازپرداختی که موفقیت‌آمیز نیستند (یعنی معیارهای بیان شده را ندارند) ثبت می‌شوند، اما برنامه‌های نرخ برای آنها اعمال نمی‌شود. به عنوان مثال: txProviderStatus == 'OK'

2. ویژگی Status را با تعریف فیلدهای زیر پیکربندی کنید:

   میدان	توضیحات
   محل پاسخگویی	محل پاسخ که در آن ویژگی مشخص شده است. مقادیر معتبر عبارتند از: متغیر جریان، سربرگ، JSON Body و XML Body.
   ارزش	ارزش پاسخ برای تعیین بیش از یک مقدار، روی + Add x (به عنوان مثال + Add Flow Variable ) کلیک کنید.

3. ویژگی Parent ID را با تعریف فیلدهای زیر پیکربندی کنید:

   میدان	توضیحات
   محل پاسخگویی	محل پاسخ که در آن ویژگی مشخص شده است. مقادیر معتبر عبارتند از: متغیر جریان، سربرگ، JSON Body و XML Body.
   ارزش	شناسه تراکنشی که برای آن بازپرداخت پردازش می شود. برای مثال، اگر کاربری محصولی را خریداری کند و سپس درخواست بازپرداخت کند، شناسه تراکنش والدین شناسه تراکنش خرید است. برای تعیین بیش از یک مقدار، روی + Add x (به عنوان مثال + Add Flow Variable ) کلیک کنید.

4. برای پیکربندی ویژگی‌های بازپرداخت اختیاری، گزینه Use Optional Refund Attributes را فعال کرده و ویژگی‌ها را پیکربندی کنید. ویژگی‌های بازپرداخت اختیاری همان ویژگی‌های تراکنش اختیاری است که در پیکربندی ویژگی‌های تراکنش تعریف شده است.

مدیریت سیاست های ثبت تراکنش با استفاده از API

بخش‌های زیر نحوه مدیریت سیاست‌های ضبط تراکنش با استفاده از API را شرح می‌دهند.

ایجاد یک خط مشی ضبط تراکنش با استفاده از API

شما یک خط مشی ضبط تراکنش را به عنوان ویژگی یک محصول API مشخص می کنید. مقدار ویژگی مشخص می کند:

• پسوند URI منبع محصول که خط مشی ضبط تراکنش به آن پیوست شده است. پسوند شامل یک متغیر الگو است که در بریس های فرفری محصور شده است. متغیر الگو توسط سرویس های API در زمان اجرا ارزیابی می شود. به عنوان مثال، پسوند URI زیر شامل متغیر الگوی {id} است.

  /reserve/{id}**
  

  در این مورد، API Services پسوند URI منبع را به‌عنوان /reserve و به دنبال آن هر زیر شاخه‌ای که با یک شناسه تعریف‌شده توسط ارائه‌دهنده API شروع می‌شود، ارزیابی می‌کند.

• منبعی در پاسخی که به آن پیوست شده است. یک محصول API می‌تواند چندین منبع داشته باشد و هر منبع می‌تواند یک خط‌مشی ثبت تراکنش متصل به پاسخ آن منبع داشته باشد.
• یک خط مشی متغیر استخراج که خط مشی ضبط تراکنش را قادر می سازد تا محتوا را از یک پیام پاسخ برای پارامترهای تراکنش که می خواهید ضبط کنید استخراج کند.

شما با ارسال یک درخواست PUT به API مدیریت https://api.enterprise.apigee.com/v1/organizations/ {org_name} /apiproducts/ {apiproduct_Id} (و نه به API کسب درآمد).

تعیین معیارهای موفقیت تراکنش با استفاده از API

شما می توانید معیارهای موفقیت تراکنش را برای تعیین زمان موفقیت آمیز بودن تراکنش (برای اهداف شارژ) مشخص کنید. تراکنش هایی که موفقیت آمیز نیستند (یعنی معیارهای بیان را برآورده می کنند) ثبت می شوند، اما برنامه های نرخ برای آنها اعمال نمی شود. برای مثال هایی از تنظیم معیارهای موفقیت تراکنش، به نمونه هایی از تنظیم معیارهای موفقیت تراکنش در خط مشی ثبت تراکنش مراجعه کنید.

شما معیار موفقیت تراکنش را به عنوان یک ویژگی محصول API مشخص می کنید. این کار را با ارسال یک درخواست PUT به API مدیریت https://api.enterprise.apigee.com/v1/organizations/ {org_name} /apiproducts/ {apiproduct_Id} (و نه به API کسب درآمد) انجام دهید.

به عنوان مثال، در درخواست زیر، اگر مقدار 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 که هزینه‌های طرح را بر اساس آن نرخ‌گذاری می‌کنید، مشخص کنید. برای مثال، اگر یک طرح کارت نرخ راه‌اندازی کنید، جایی که برای هر تراکنش از توسعه‌دهنده هزینه دریافت می‌کنید، می‌توانید نرخ آن را بر اساس یک ویژگی سفارشی مانند تعداد بایت‌های ارسال شده در یک تراکنش تنظیم کنید. هنگامی که یک طرح نرخ ایجاد می کنید، می توانید یک یا چند ویژگی سفارشی را مشخص کنید که بر اساس آن نرخ خود را برای طرح تعیین کنید. با این حال، هر محصول خاص در یک طرح نرخ، تنها می‌تواند یک ویژگی سفارشی داشته باشد که بر اساس آن نرخ برای طرح تعیین شود.

شما ویژگی های سفارشی را به عنوان ویژگی های یک محصول API مشخص می کنید. این کار را با ارسال یک درخواست PUT به API مدیریت https://api.enterprise.apigee.com/v1/organizations/ {org_name} /apiproducts/ {apiproduct_Id} (و نه به API کسب درآمد) انجام دهید.

برای هر ویژگی سفارشی که به یک محصول API اضافه می کنید، باید یک نام و یک مقدار مشخصه را مشخص کنید. نام باید به شکل MINT_CUSTOM_ATTRIBUTE_ {num} باشد که در آن {num} یک عدد صحیح است.

به عنوان مثال، درخواست زیر سه ویژگی سفارشی را مشخص می کند.

$ 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

نمونه هایی از تنظیم معیارهای موفقیت تراکنش در خط مشی ثبت تراکنش

جدول زیر نمونه هایی از تراکنش های موفق و ناموفق را بر اساس عبارت معیار موفقیت تراکنش و مقدار txProviderStatus ارائه شده توسط پراکسی API ارائه می دهد. txProviderStatus متغیر داخلی است که کسب درآمد از آن برای تعیین موفقیت تراکنش استفاده می کند.