הגדרה של תוכנית תעריפים עם מאפיינים מותאמים אישית

אתם צופים במסמכי העזרה של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info

מבוא

במקרים מסוימים, יכול להיות שתצטרכו שמוני עסקאות יתבססו על משתנה או ערך מותאם אישית. לדוגמה, יכול להיות שתצטרכו:

• לחייב מפתחים בסכום משתנה על סמך ערך שסופק בהודעה של קריאה ל-API. לדוגמה, יכול להיות שתרצו לחייב מפתחי אפליקציות על סמך מספר הבייטים המועברים בבקשת ה-API.
• איחוד כמה קריאות ל-API בטרנזקציה אחת.

באמצעות תוכניות תמחור עם מאפיינים מותאמים אישית, אפשר לזהות ערך בהודעה של קריאה ל-API שמשמשת כמספר עסקאות, ומשמש לחישוב מספר העסקאות והחיובים.

יש תמיכה בתוכניות תעריפים עם מאפיינים מותאמים אישית:

• מחירון עם מאפיין מותאם אישית
• התראה מתכווננת עם מאפיין מותאם אישית

אפשר להגדיר עד 10 מאפיינים מותאמים אישית לכל תוכנית תעריפים.

הסבר על חישובים של מאפיינים מותאמים אישית

האופן שבו ערך המאפיין המותאם אישית נלקח בחשבון במספרי העסקאות ובחיובים של תוכנית התעריפים תלוי במודל החיוב, כפי שמתואר בטבלה הבאה.

מודל טעינה	חישוב של מאפיין מותאם אישית
תעריף קבוע וחבילות נפח	custom attribute number * rate = charge to developer כשמשתמשים בשיעור קבוע, מספר המאפיין המותאם אישית הופך למספר העסקאות שמוכפל בשיעור. בתוכנית 'נפח נתונים מוגבל', מספר העסקאות בפס מוגדל במספר המאפיין המותאם אישית, והמפתח מחויב על מספר העסקאות הזה. לדוגמה, אם ערך המאפיין המותאם אישית בהודעה הוא 10, המפתח יחויב עבור 10 עסקאות, ו-10 עסקאות יתווספו לספירת התדרים הנוכחית. אם למפתח היו רק 6 עסקאות בטווח הנוכחי, הערך של 6 מוכפל בשיעור של אותו טווח. 4 הנותרים עוברים לפס הבא ומוכפלים בשיעור של אותו פס. בתוכנית עם חלוקה לנפחי אחסון, אם לפס ההנחה האחרון יש מגבלה (לא 'ללא הגבלה') ועסקה חורגת מהמגבלה הזו, מתרחשים שני דברים: המפתח מקבל את הסכום הנוסף בחינם. אפליקציית הפיתוח תיחסם מביצוע קריאות נוספות ל-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, ומציינים פרמטר של דירוג מותאם אישית.

באיור הבא מוצג הקשר בין המאפיין המותאם אישית שמוגדר במדיניות של תיעוד העסקאות לבין ההגדרה של תוכנית התעריפים. ההודעה הניתנת להתאמה עם קשר של תוכנית תעריפים למאפיין מותאם אישית דומה, אבל הערך של תוכנית התעריפים עם פס נפח לא רלוונטי.

איך יוצרים את ערך המאפיין בהתאמה אישית בהודעה

מדיניות הרישום של העסקאות יכולה לחפש את הערך של המאפיין המותאם אישית בכמה מקומות, כמו כותרת התגובה, גוף התגובה או משתני התהליך שהוגדרו מראש בתגובה. (הבקשה לא זמינה כי העסקה לא רשמית עד שמקבלים תשובה מוצלחת). בהמשך מפורטות דוגמאות להוספת כותרת תגובה עם הערך המספרי שלה להודעה. בשני המקרים, נשתמש במדיניות הקצאת הודעות בשילוב עם משתנים.

הוספת גודל המטען הייעודי (payload) של הבקשה לכותרת התגובה

בכל בקשה להעברת הודעה יש משתנה 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 בכל אפליקציית פיתוח, באופן הבא:

כשמשתמשים במדיניות לאימות מפתח API (שנדרשת למונטיזציה), הערך הזה מאוחסן במשתנה שנקרא verifyapikey.{policy_name}.apprating. באמצעות המדיניות 'הקצאת הודעה' שמצורפת לתגובה של נקודת הקצה של שרת ה-proxy, אפשר ליצור כותרת בשם 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, כמו שמתואר בסעיפים הבאים.

הגדרת תוכנית התראות ניתנת להתאמה עם מאפיינים מותאמים אישית באמצעות ממשק המשתמש

מגדירים תוכניות התראות שניתן לשנות באמצעות מאפיינים מותאמים אישית, כפי שמתואר בהמשך.

ציון פרטים של תוכנית תעריפים עם מאפיינים מותאמים אישית באמצעות ה-API

מבצעים את השלבים המוקדמים הבאים:

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