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

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

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

מבוא

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

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

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

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

הגדרת מדיניות לתיעוד טרנזקציות

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

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

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

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

   txProviderStatus == 'OK'

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

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

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

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

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

שדה	Value
קריטריונים להצלחה עם עסקאות	txProviderStatus == 'OK'
סטטוס: משאב API	**
סטטוס: מיקום התגובה	משתנה זרימה
סטטוס: משתנה זרימה	response.reason.phrase

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

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

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

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

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

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

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

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

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

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

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

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

משאב	מיקום התגובה	Value
reserve/{id}**	כותרת	session_id
/charge/{id}**	כותרת	reference_id

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

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

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

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

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

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

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

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

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

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

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

ניהול המדיניות בנושא תיעוד עסקאות באמצעות ה-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 הוא המשתנה הפנימי שמשמש את המונטיזציה כדי לקבוע את הצלחת העסקאות.

ביטוי של קריטריונים להצלחה	ביטוי חוקי?	ערך txProviderStatus משרת API של API	תוצאת ההערכה
null	true	"200"	false
""	false	"200"	false
" "	false	"200"	false
"sdfsdfsdf"	false	"200"	false
"txProviderStatus =='100'"	true	"200"	false
"txProviderStatus =='200'"	true	"200"	true
"true"	true	"200"	true
"txProviderStatus=='OK' OR txProviderStatus=='Not Found' OR txProviderStatus=='Bad Request'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Not Found"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"bad request"	true
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Redirect"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"heeeelllooo"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus == 100"	true	"200"	false