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

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

مقدمه

در برخی موارد، ممکن است نیاز داشته باشید که شمارنده‌های تراکنش براساس مقدار متغیر یا سفارشی باشد. برای مثال، ممکن است لازم باشد:

  • مبلغ متغیری را براساس مقداری که در پیام تماس API ارائه شده است از توسعه‌دهندگان کسر کنید. برای مثال، ممکن است بخواهید براساس تعداد بایت‌های انتقال‌یافته در درخواست API از توسعه‌دهندگان برنامه هزینه دریافت کنید.
  • چندین فراخوانی API را در یک تراکنش واحد دسته‌بندی کنید.

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

طرح‌های نرخ زیر با مشخصه‌های سفارشی پشتیبانی می‌شوند:

  • کارت نرخ با مشخصه سفارشی
  • اعلان قابل‌تنظیم با مشخصه سفارشی

می‌توانید حداکثر ده مشخصه سفارشی برای هر طرح نرخ تنظیم کنید.

درک محاسبات مشخصه سفارشی

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

مدل شارژ محاسبه مشخصه سفارشی
نرخ ثابت و حجم دسته‌بندی‌شده

custom attribute number * rate = charge to developer

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

در طرح «حجم دسته‌بندی‌شده»، اگر آخرین دسته حجم دارای محدودیت باشد (نامحدود نباشد) و تراکنشی از آن محدودیت فراتر رود، دو اتفاق می‌افتد:

بسته

ازآنجایی‌که هزینه دسته‌ها براساس گروه محاسبه می‌شود، نه براساس تراکنش، محاسبه زیر انجام می‌شود:

custom attribute number = amount added to bundle count

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

اگر آخرین بسته محدودیت داشته باشد (نامحدود نباشد) و تراکنشی از آن محدودیت فراتر رود، دو اتفاق می‌افتد:

اعلان‌های قابل‌تنظیم

برای اعلان قابل‌تنظیم، محاسبات زیر انجام می‌شود:

custom attribute number = amount added to transaction count

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

جایی که طرح نرخ مقدار مشخصه سفارشی را دریافت می‌کند

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

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

جریان سطح بالا به این صورت است:

  1. مشخصه‌های سفارشی را هنگام افزودن محصول API تعریف کنید.
  2. بسته محصول API ایجاد کنید که حاوی محصول باشد.
    در خط‌مشی ضبط تراکنش برای بسته محصول «میانای برنامه‌سازی کاربردی»، مشخصه‌های سفارشی را که برای تعریف طرح‌های نرخ استفاده می‌شوند اضافه کنید.
  3. طرح نرخی از نوع جدول نرخ یا اعلان قابل‌تنظیم برای بسته محصول API ایجاد کنید و پارامتر رده‌بندی سفارشی را مشخص کنید.

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

نحوه تولید مقدار مشخصه سفارشی در پیام

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

افزودن اندازه بار داده درخواست به سرایند پاسخ

در هر درخواست پیام، متغیر client.received.content.length وجود دارد که شامل تعداد بایت‌های بار درخواست است. با پیوست کردن خط‌مشی «اختصاص پیام» به پاسخ «نقطه پایانی پراکسی»، می‌توانیم سرصفحه پاسخی به نام messageSize تولید کنیم که حاوی مقدار طول است:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="messageSize">{client.received.content.length}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

افزودن مقدار مشخصه سفارشی برنامه به سرایند

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

هنگام استفاده از خط‌مشی «درستی‌سنجی کلید API» (که برای درآمدزایی الزامی است)، این مقدار در متغیری به‌نام verifyapikey.{policy_name}.apprating ذخیره می‌شود. بااستفاده از خط‌مشی «تخصیص پیام» پیوست‌شده به پاسخ «نقطه پایانی پراکسی»، می‌توانید سرایندی به‌نام apprating تولید کنید که حاوی مقدار apprating برنامه است:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="apprating">{verifyapikey.Verify-API-Key-1.apprating}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

درحال راه‌اندازی طرح نرخ

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

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

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

Edge

برای پیکربندی طرح کارت نرخ با مشخصه‌های سفارشی بااستفاده از «میانای کاربر Edge»:

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

برای اطلاعات بیشتر، پیکربندی جزئیات طرح کارت نرخ بااستفاده از واسط کاربر را ببینید.

Classic Edge (ابر خصوصی)

از مراحل زیر برای ایجاد «کارت نرخ» با طرح «مشخصه سفارشی» بااستفاده از «میانای کاربری کلاسیک Edge» استفاده کنید:

  1. در خط‌مشی ضبط تراکنش محصول API، ویژگی‌های سفارشی را که برای تعریف طرح‌های نرخ استفاده می‌شوند اضافه کنید. برای جزئیات، مقدمه این موضوع و همچنین ایجاد خط‌مشی ضبط تراکنش را ببینید. این کار را برای هر محصول API که می‌خواهید در بسته API بگنجانید انجام دهید.
  2. وقتی محصولات API و خط‌مشی‌های ضبط تراکنش دقیقاً به همان شکلی که می‌خواهید پیکربندی شدند، بسته API حاوی محصول را ایجاد کنید. ایجاد بسته‌های API را ببینید.
  3. طرح نرخی برای بسته API ایجاد کنید و نوع طرح نرخ کارت نرخ با مشخصه سفارشی را انتخاب کنید.
  4. روی پیوند کارت نرخ کلیک کنید. با این کار، پنجره «جدول نرخ خدمات» باز می‌شود.

  5. مشخصه سفارشی را در منوِ کرکره‌ای «مشخصه سفارشی» انتخاب کنید. این منو مشخصه‌های سفارشی ایجادشده برای محصول را در خط‌مشی ضبط تراکنش فهرست می‌کند. توسعه‌دهنده براساس مقدار مشخصه سفارشی انتخاب‌شده در هر تراکنش مورد کسر هزینه قرار می‌گیرد.‫
    (مقدار مشخصه * نرخ = کسر هزینه از توسعه‌دهنده)
  6. به‌صورت اختیاری، طرحی رایگان با ویژگی‌های ممتاز را همان‌طور که در مشخص کردن جزئیات طرح کارت نرخ توضیح داده شده است راه‌اندازی کنید.
  7. مدل شارژ را همان‌طور که در جزئیات طرح کارت نرخ مشخص شده است راه‌اندازی کنید. بااین‌حال، توجه داشته باشید که برای نوع طرح نرخ «کارت نرخ با مشخصه سفارشی»، مدل شارژ براساس مشخصه سفارشی‌ای است که انتخاب می‌کنید. برای مثال، اگر «نرخ ثابت» را به‌عنوان مدل شارژ انتخاب کنید، براساس مشخصه سفارشی، مثل تعداد بایت‌های منتقل‌شده در هر تراکنش، نرخ ثابتی از توسعه‌دهنده کسر می‌شود (نه نرخ ثابت برای هر تراکنش). برای اطلاعات بیشتر، محاسبات را ببینید.
  8. روی ذخیره پیش‌نویس کلیک کنید.
    فقط زمانی طرح را منتشر کنید که کاملاً مطمئن باشید نهایی است. برای اطلاعات درباره تنظیم «تاریخ انتشار» و انتشار طرح، به انتشار طرح‌های نرخ مراجعه کنید.

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

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

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

Edge

برای پیکربندی طرح کارت نرخ با مشخصه‌های سفارشی بااستفاده از «میانای کاربر Edge»:

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

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

Classic Edge (ابر خصوصی)

برای پیکربندی طرح کارت نرخ با مشخصه‌های سفارشی بااستفاده از «واسط کاربر Classic Edge»:

  1. در خط‌مشی ضبط تراکنش محصول API، ویژگی‌های سفارشی را که برای تعریف طرح‌های نرخ استفاده می‌شوند اضافه کنید. برای جزئیات، مقدمه این موضوع و همچنین ایجاد خط‌مشی ضبط تراکنش را ببینید. این کار را برای هر محصول API که می‌خواهید در بسته API بگنجانید انجام دهید.
  2. وقتی محصولات API و خط‌مشی‌های ضبط تراکنش دقیقاً به همان شکلی که می‌خواهید پیکربندی شدند، بسته API حاوی محصول را ایجاد کنید. ایجاد بسته‌های API را ببینید.
  3. طرح نرخی برای بسته API ایجاد کنید و نوع طرح نرخ اعلان قابل‌تنظیم با ویژگی سفارشی را انتخاب کنید.
  4. روی پیوند جزئیات کلیک کنید. با این کار، پنجره «اعلان قابل‌تنظیم» باز می‌شود.

  5. مشخصه سفارشی را در منوِ کرکره‌ای مشخصه سفارشی انتخاب کنید. این منو فهرست مشخصه‌های سفارشی ایجادشده برای محصول را در خط‌مشی ضبط تراکنش نشان می‌دهد. تعداد کل تراکنش‌های توسعه‌دهنده براساس مقدار ویژگی سفارشی انتخاب‌شده در هر تراکنش محاسبه می‌شود.
  6. پایه انبوهش را روی دوره زمانی‌ای تنظیم کنید که حجم تراکنش‌ها در آن انبوهش می‌شود. عددی بین ۱ تا ۲۴ ماه انتخاب کنید. این مقدار به‌طور پیش‌فرض روی ۱ ماه تنظیم می‌شود.
  7. روی اعمال و بستن کلیک کنید.
  8. روی ذخیره پیش‌نویس کلیک کنید.
    فقط زمانی طرح را منتشر کنید که کاملاً مطمئن باشید نهایی است. برای اطلاعات درباره تنظیم «تاریخ انتشار» و انتشار طرح، به انتشار طرح‌های نرخ مراجعه کنید.

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

مشخص کردن جزئیات طرح قیمت با مشخصه‌های سفارشی بااستفاده از میانای برنامه‌سازی کاربردی

مراحل پیش‌نیاز زیر را انجام دهید:

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

سپس از API برای ایجاد طرح نرخ استفاده می‌کنید.

وقتی طرح نرخ را ایجاد می‌کنید، جزئیات طرح نرخ را با مشخصه‌های سفارشی تعیین می‌کنید. جزئیات را در دارایی ratePlanDetails در بدنه درخواست در تماس با /organizations/{org_name}/monetization-packages/{package_id}/rate-plans مشخص می‌کنید. در جزئیات، مقدار پارامتر رده‌بندی را مشخص می‌کنید که نام مشخصه سفارشی را شناسایی می‌کند. همچنین می‌توانید مقدار پارامتر رده‌بندی را مشخص کنید که مشخصه سفارشی را طی بازه زمانی مشخصی تجمیع می‌کند.

برای فهرست کامل گزینه‌های جزئیات طرح نرخ، تنظیمات پیکربندی جزئیات طرح نرخ را ببینید.

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

$ curl -H "Content-Type:application/json" -X POST -d \
'{
   "name": "Custom attribute-based rate card plan",
   "developer":null,
   "developerCategory":null,
   "currency": {
     "id" : "usd"
     },     
   "description": "Custom attribute-based rate card plan",
   "displayName" : "Custom attribute-based rate card plan",
   "frequencyDuration": "1",
   "frequencyDurationType": "MONTH",
   "earlyTerminationFee": "10",
   "monetizationPackage": {
      "id": "location"
        },
      "organization": {
       "id": "{org_name}"
      },    
   "paymentDueDays": "30",
   "prorate": "false",
   "published": "false",     
   "ratePlanDetails":[
      {
        "currency":{
           "id":"usd"
        },
      "duration":1,
      "durationType":"MONTH",
      "meteringType":"VOLUME",
      "paymentDueDays":"30",
      "ratingParameter":"messageSize",
      "ratingParameterUnit":"MB",
      "organization":{
         "id":"{org_name}"
      },
      "ratePlanRates":[
         {
           "rate":0.15,
           "startUnit":0,
           "type":"RATECARD",
           "endUnit":1000
         },
         {
           "rate":0.1,
           "startUnit":1000,
           "type":"RATECARD",
           "endUnit":null
         }
      ],
      "freemiumUnit":0,
      "freemiumDuration":0,
      "freemiumDurationType":"MONTH",
      "type":"RATECARD",
      "customPaymentTerm":false
      }
    ],
    "freemiumUnit":0,
    "freemiumDuration":0,
    "freemiumDurationType":"MONTH",
    "contractDuration":"1",
    "contractDurationType":"YEAR", 
    "recurringStartUnit": 1,
    "recurringType": "CALENDAR",
    "recurringFee": "10",
    "setUpFee": "10",
    "startDate": "2013-09-15 00:00:00",
    "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans" \
-u email:password

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

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "AdjustableNotification",
     "displayName": "Custom attribute-based adjustable notification plan",
     "description": "Custom attribute-based adjustable notification plan",
     "published": "true",  
     "organization": {
      "id": "myorg"
     },
     "startDate": "2016-04-15 00:00:00",
     "type": "STANDARD",
     "monetizationPackage": {
        "id": "p1",
        "name": "test"
     },
     "currency": {
        "id" : "usd",
        "name" : "USD"
     },
     "ratePlanDetails": [
        {
           "type": "USAGE_TARGET",
           "meteringType": "DEV_SPECIFIC",
           "duration": 1,
           "durationType": "MONTH",
           "ratingParameter": "messageSize",
           "ratingParameterUnit": "MB",
           "organization": {
             "id": "myorg"
           },
           "currency": {
             "id": "usd",
             "name": "USD"
           }
        }
     ]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/monetization-packages/p1/rate-plans"  \
-u email:password