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

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

מבוא

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

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

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

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

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

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

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

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

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

   txProviderStatus == 'OK'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2. כדי להגדיר את המאפיין Status, מגדירים את השדות הבאים:

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

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

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

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

ניהול המדיניות בנושא תיעוד טרנזקציות באמצעות ה-API

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

יצירת מדיניות בנושא תיעוד טרנזקציות באמצעות ה-API

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

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

  /reserve/{id}**
  

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

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

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