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

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

مقدمه

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

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

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

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

• کارت امتیاز با ویژگی سفارشی
• اعلان قابل تنظیم با ویژگی سفارشی

شما می توانید حداکثر ده ویژگی سفارشی را در هر طرح نرخ تنظیم کنید.

درک محاسبات ویژگی های سفارشی

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

مدل شارژ	محاسبه ویژگی سفارشی
نرخ ثابت و حجم باند	custom attribute number * rate = charge to developer برای یک نرخ ثابت، شماره ویژگی سفارشی به تعداد تراکنش هایی تبدیل می شود که در برابر نرخ ضرب می شوند. برای Volume Banded، تعداد تراکنش‌ها در یک باند با شماره ویژگی سفارشی افزایش می‌یابد و توسعه‌دهنده برای آن تعداد تراکنش هزینه دریافت می‌کند. به عنوان مثال، اگر یک مقدار مشخصه سفارشی در پیام 10 باشد، توسعه دهنده برای 10 تراکنش هزینه دریافت می کند و 10 تراکنش به تعداد باند فعلی اضافه می شود. اگر توسعه دهنده تنها 6 تراکنش در باند فعلی باقی مانده باشد، 6 در نرخ آن باند ضرب می شود. 4 باقیمانده به باند بعدی می روند و در نرخ آن باند ضرب می شوند. در طرح Volume Banded، اگر آخرین باند حجم دارای محدودیت باشد ("نامحدود" نیست) و تراکنش از آن حد فراتر رود، دو اتفاق می افتد: توسعه دهنده مبلغ "بیش از" را رایگان دریافت می کند. برنامه توسعه‌دهنده از برقراری تماس‌های بیشتر با API تا زمان بازنشانی دوره برنامه مسدود شده است. ببینید چه زمانی کارمزدهای تکراری دریافت می‌شود و طرح‌های بسته بازنشانی می‌شوند؟ برای جزئیات مربوط به زمان تنظیم مجدد برنامه ها.
بسته ها	از آنجایی که بسته‌ها توسط گروه شارژ می‌شوند، نه توسط تراکنش، محاسبه زیر انجام می‌شود: custom attribute number = amount added to bundle count به عنوان مثال، اگر شماره ویژگی سفارشی در پیام 10 باشد، 10 به تعداد تراکنش های استفاده شده در بسته اضافه می شود. اگر توسعه‌دهنده تنها 6 تراکنش در بسته فعلی باقی مانده باشد، آن بسته پر می‌شود و تعداد بسته بعدی 4 افزایش می‌یابد. نرخ آن بسته بعدی، در صورت وجود، محاسبه می‌شود. اگر آخرین بسته دارای یک محدودیت باشد ("نامحدود" نیست) و یک تراکنش از آن حد فراتر رود، دو اتفاق می افتد: توسعه دهنده مبلغ "بیش از" را رایگان دریافت می کند. برنامه توسعه‌دهنده از برقراری تماس‌های بیشتر با API تا زمان بازنشانی دوره برنامه مسدود شده است. ببینید چه زمانی کارمزدهای تکراری دریافت می‌شود و طرح‌های بسته بازنشانی می‌شوند؟ برای جزئیات مربوط به زمان تنظیم مجدد برنامه ها.
اعلان های قابل تنظیم	برای اعلان قابل تنظیم، محاسبه زیر رخ می دهد: custom attribute number = amount added to transaction count به عنوان مثال، اگر شماره ویژگی سفارشی در پیام 10 باشد، 10 به تعداد کل تراکنش ها اضافه می شود.

جایی که طرح نرخ ارزش ویژگی سفارشی را دریافت می کند

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

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

در اینجا جریان سطح بالا آمده است:

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

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

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

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

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

در هر درخواست پیام، یک متغیر client.received.content.length وجود دارد که شامل تعداد بایت‌های بار درخواست است. با پیوست کردن یک خط مشی Assign Message به پاسخ Proxy Endpoint، می‌توانیم یک هدر پاسخ به نام 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 در هر برنامه توسعه دهنده قرار دهید، به شرح زیر است:

هنگام استفاده از خط‌مشی Verify API Key (که برای کسب درآمد ضروری است)، این مقدار در متغیری به نام verifyapikey.{policy_name}.apprating ذخیره می‌شود. با استفاده از خط مشی Assign Message پیوست شده به پاسخ Proxy Endpoint، می توانید سرصفحه ای به نام 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 UI یا Classic Edge UI پیکربندی کنید، همانطور که در بخش های زیر توضیح داده شده است.

پیکربندی یک برنامه اعلان قابل تنظیم با ویژگی های سفارشی با استفاده از رابط کاربری

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

تعیین جزئیات برای یک طرح نرخ با ویژگی های سفارشی با استفاده از API

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

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

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

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

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

به عنوان مثال، موارد زیر بر اساس یک ویژگی سفارشی به نام messageSize ، یک Rate Card با طرح ویژگی سفارشی ایجاد می کند (به موارد پررنگ مراجعه کنید).

$ 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