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

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

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

مقدمه

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

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

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

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

پیکربندی سیاست ثبت تراکنش

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

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

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

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

   txProviderStatus == 'OK'

2. ویژگی وضعیت (Status) حاوی مقداری است که توسط عبارت پیکربندی شده در فیلد «معیارهای موفقیت تراکنش» (Transaction Success Criteria) استفاده می‌شود. ویژگی وضعیت (Status) را با تعریف فیلدهای زیر پیکربندی کنید:

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

3. برای پیکربندی ویژگی‌های اختیاری تراکنش، گزینه‌ی « استفاده از ویژگی‌های اختیاری» را فعال کنید و هر یک از ویژگی‌های تراکنش تعریف‌شده در جدول زیر را پیکربندی کنید.

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

برای مثال، با تنظیم مقادیر زیر، monetization مقدار متغیر flow را از پاسخ پیام در متغیری به نام response.reason.phrase دریافت می‌کند. اگر مقدار OK باشد و سیاست Monetization Limits Check به درخواست پروکسی API ProxyEndpoint پیوست شده باشد، monetization آن را به عنوان یک تراکنش در نظر می‌گیرد.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

برای پیکربندی بازپرداخت‌ها، گزینه‌ی « استفاده از ویژگی‌های بازپرداخت» را فعال کنید و جزئیات بازپرداخت را تعریف کنید:

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

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

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

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

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

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

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

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

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

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

شما یک سیاست ثبت تراکنش را به عنوان یک ویژگی از یک محصول API مشخص می‌کنید. مقدار این ویژگی موارد زیر را مشخص می‌کند:

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

  /reserve/{id}**

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

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

شما می‌توانید با ارسال یک درخواست PUT به API مدیریتی https://api.enterprise.apigee.com/v1/organizations/ {org_name} /apiproducts/ {apiproduct_Id} (و نه به یک API کسب درآمد)، ویژگی سیاست ثبت تراکنش را به یک محصول 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 متغیر داخلی است که کسب درآمد از آن برای تعیین موفقیت تراکنش استفاده می‌کند.