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

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

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

مقدمه

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

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

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

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

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

همان‌طور که در زیر توضیح داده شده است، به صفحه «دسته‌های محصول» دسترسی پیدا کنید.

پیکربندی مشخصه‌های تراکنش

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

1. در فیلد معیارهای موفقیت تراکنش، عبارت را براساس مقدار مشخصه «وضعیت» (در ادامه توضیح داده شده است) برای تعیین زمان موفقیت‌آمیز بودن تراکنش (برای اهداف کسر هزینه) مشخص کنید. تراکنش‌هایی که موفق نیستند (یعنی معیارهای عبارت را برآورده نمی‌کنند) ثبت می‌شوند، اما طرح‌های نرخ به آن‌ها اعمال نمی‌شود. برای مثال:

   txProviderStatus == 'OK'

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

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

3. برای پیکربندی مشخصه‌های اختیاری تراکنش، کلید استفاده از مشخصه‌های اختیاری را فعال کنید و هریک از مشخصه‌های تراکنش تعریف‌شده در جدول زیر را پیکربندی کنید.

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

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

درحال پیکربندی مشخصه‌های سفارشی

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

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

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

برای پیکربندی مشخصه‌های سفارشی، کلید استفاده از مشخصه‌های سفارشی را فعال کنید و حداکثر ۱۰ مشخصه سفارشی تعریف کنید. برای هر مشخصه سفارشی که در خط‌مشی ضبط تراکنش اضافه می‌کنید، باید اطلاعات زیر را مشخص کنید.

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

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

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

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

برای پیکربندی مشخصه‌های سفارشی، کلید تغییر وضعیت استفاده از شناسه‌های تراکنش یکتا را فعال کنید و تراکنش‌ها را پیوند دهید. برای هر تراکنش، منبع، مکان پاسخ، و مقدار مشخصه‌ای را که با مقادیر متناظر در تراکنش‌های دیگر پیوند داده شده است مشخص می‌کنید.

برای مثال، فرض کنید فراخوانی API رزرو و فراخوانی API کسر هزینه به‌صورت زیر پیوند داده شده‌اند: فیلدی به‌نام session_id در سرایند پاسخ از API رزرو با سرایند پاسخ به‌نام reference_id از API کسر هزینه مطابقت دارد. در این مورد، ممکن است ورودی‌های بخش «پیوند دادن منابع با شناسه تراکنش یکتا» را به‌صورت زیر تنظیم کنید:

درحال پیکربندی استرداد مبلغ

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

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

برای پیکربندی استرداد مبلغ، کلید استفاده از مشخصه‌های استرداد مبلغ را فعال کنید و جزئیات استرداد مبلغ را تعریف کنید:

1. معیارهای استرداد مبلغ را با تعریف کردن فیلدهای زیر مشخص کنید:

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

2. با تعریف کردن فیلدهای زیر، مشخصه وضعیت را پیکربندی کنید:

   فیلد	شرح
   مکان پاسخ	مکان پاسخ که مشخصه در آن مشخص شده است. مقادیر معتبر شامل این موارد است: متغیر جریان، سرایند، بدنه JSON، و بدنه XML.
   مقدار	مقدار پاسخ. برای مشخص کردن بیش‌از یک مقدار، روی + افزودن x (برای نمونه، + افزودن متغیر جاری‌سازی) کلیک کنید.

3. مشخصه شناسه والد را با تعریف کردن فیلدهای زیر پیکربندی کنید:

   فیلد	شرح
   مکان پاسخ	مکان پاسخ که مشخصه در آن مشخص شده است. مقادیر معتبر شامل این موارد است: متغیر جریان، سرایند، بدنه JSON، و بدنه XML.
   مقدار	شناسه تراکنشی که برای آن استرداد مبلغ پردازش می‌شود. برای مثال، اگر کاربری محصولی را خریداری کند و سپس درخواست استرداد مبلغ کند، «شناسه تراکنش اصلی» شناسه تراکنش خرید است. برای مشخص کردن بیش‌از یک مقدار، روی + افزودن x (برای نمونه، + افزودن متغیر جاری‌سازی) کلیک کنید.

4. برای پیکربندی مشخصه‌های اختیاری استرداد مبلغ، دکمه استفاده از مشخصه‌های اختیاری استرداد مبلغ را فعال کنید و مشخصه‌ها را پیکربندی کنید. مشخصه‌های اختیاری استرداد مبلغ همان مشخصه‌های اختیاری تراکنش است، همان‌گونه که در پیکربندی مشخصه‌های تراکنش تعریف شده است.

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

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

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

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

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

  /reserve/{id}**

  در این مورد، «خدمات API» پسوند نشانی وب منبع را به‌صورت /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 مشخص می‌کنید. این کار را با صدور درخواست 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 متغیر داخلی است که درآمدزایی برای تعیین موفقیت تراکنش استفاده می‌کند.