הגדרת מדיניות לתיעוד עסקאות

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

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

מבוא

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

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

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

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

הגדרת מדיניות להקלטת עסקאות

נכנסים לדף 'חבילות מוצרים' כמו שמתואר בהמשך.

הגדרת מאפייני עסקאות

בקטע מאפייני העסקה, מציינים את הקריטריונים שמצביעים על עסקה מוצלחת למונטיזציה.

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

   txProviderStatus == 'OK'

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

   שדה	תיאור
   API Resource	תבניות URI שמוגדרות במוצר ה-API וישמשו לזיהוי טרנזקציות שמתבצעת עליהן מונטיזציה.
   מיקום התשובה	המיקום של התגובה שבה מצוין המאפיין. הערכים התקינים כוללים: משתנה של Flow, כותרת, גוף JSON וגוף XML.
   ערך	ערך התשובה. כדי לציין יותר מערך אחד, לוחצים על + הוספת x (לדוגמה, + הוספת משתנה של זרימת נתונים).

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

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

לדוגמה, אם מגדירים את הערכים הבאים, מונטיזציה מקבלת את הערך של משתנה הזרימה מהתגובה להודעה במשתנה שנקרא response.reason.phrase. אם הערך תקין, והמדיניות לבדיקת מגבלות המונטיזציה מצורפת לבקשת ProxyEndpoint של ה-proxy ל-API, המונטיזציה סופרת את הבקשה כעסקה.

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

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

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

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

כדי להגדיר מאפיינים מותאמים אישית, מפעילים את המתג Use Custom Attributes (שימוש במאפיינים מותאמים אישית) ומגדירים עד 10 מאפיינים מותאמים אישית. לכל מאפיין מותאם אישית שכוללים במדיניות תיעוד העסקאות, צריך לציין את הפרטים הבאים.

קישור משאבים עם מזהה עסקה ייחודי

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

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

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

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

לדוגמה, נניח שקריאת ה-API לביצוע הזמנה וקריאת ה-API לחיוב מקושרות באופן הבא: שדה בשם session_id בכותרת התגובה מ-API לביצוע הזמנה תואם לכותרת תגובה בשם reference_id מ-API לחיוב. במקרה כזה, אפשר להגדיר את הערכים בקטע Link Resources with Unique Transaction ID (קישור מקורות עם מזהה עסקה ייחודי) באופן הבא:

הגדרת החזרים כספיים

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

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

כדי להגדיר החזרים כספיים, מפעילים את המתג Use Refund Attributes (שימוש במאפייני החזר כספי) ומגדירים את פרטי ההחזר הכספי:

1. מגדירים את הקריטריונים להחזר כספי על ידי הגדרת השדות הבאים:

   שדה	תיאור
   מיקום התשובה	משאב לעסקת ההחזר הכספי. אם מוצר ה-API מספק כמה משאבים, אפשר לבחור רק את המשאב שמבצע את ההחזר הכספי.
   קריטריונים להצלחת ההחזר הכספי	ביטוי שמבוסס על הערך של מאפיין הסטטוס (שמתואר בהמשך) כדי לקבוע מתי עסקת ההחזר הכספי הושלמה (למטרות חיוב). עסקאות של החזרים כספיים שלא צלחו (כלומר, שלא עומדות בקריטריונים של הביטוי) מתועדות, אבל תוכניות התמחור לא חלות עליהן. לדוגמה: txProviderStatus == 'OK'

2. מגדירים את מאפיין הסטטוס באמצעות השדות הבאים:

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

3. מגדירים את המאפיין מזהה פריט אב על ידי הגדרת השדות הבאים:

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

4. כדי להגדיר מאפייני החזר אופציונליים, מפעילים את המתג Use Optional Refund Attributes (שימוש במאפייני החזר אופציונליים) ומגדירים את המאפיינים. מאפייני ההחזר האופציונליים זהים למאפייני העסקה האופציונליים, כפי שמוגדרים במאמר הגדרת מאפייני עסקה.

ניהול מדיניות תיעוד העסקאות באמצעות ה-API

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

יצירת מדיניות של תיעוד עסקאות באמצעות API

מגדירים מדיניות של תיעוד עסקאות כמאפיין של מוצר API. הערך של המאפיין מזהה:

• סיומת ה-URI של משאב המוצר שאליו מצורפת מדיניות תיעוד העסקאות. הסיומת כוללת משתנה תבנית שמוקף בסוגריים מסולסלים. המשתנה pattern מוערך על ידי API Services בזמן הריצה. לדוגמה, סיומת ה-URI הבאה כוללת את משתנה התבנית {id}.

  /reserve/{id}**

  במקרה הזה, API Services מעריך את הסיומת של ה-URI של המשאב כ-/reserve ואחריו כל ספריית משנה שמתחילה במזהה שהוגדר על ידי ספק ה-API.

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

כדי להוסיף את מאפיין מדיניות תיעוד העסקאות למוצר API, שולחים בקשת PUT אל Management API‏ https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (ולא אל API למונטיזציה).

ציון קריטריונים להצלחת העסקה באמצעות ה-API

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

אתם מציינים את קריטריוני ההצלחה של העסקה כמאפיין של מוצר API. כדי לעשות זאת, שולחים בקשת PUT ל-Management API‏ https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (ולא ל-Monetization 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 אל Management API‏ https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (ולא אל Monetization 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 שמוחזר על ידי proxy ל-API. ‫txProviderStatus הוא המשתנה הפנימי שמשמש למונטיזציה כדי לקבוע אם העסקה הצליחה.