הנחיות להטמעה בצד הלקוח

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

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

התחברות לנקודת קצה ל-API של Universal Ledger

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

השמות של נקודות הקצה האזוריות הם בפורמט הבא:

universalledger.REGION.rep.googleapis.com

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

הטופולוגיה של הרשת וזמינות גבוהה

רשת Universal Ledger מורכבת מכמה מאמתים שפזורים בכמה אזורים ותחומים, כדי להבטיח זמינות גבוהה של הרשת כולה.

  • כשלים באזור: אם מאמת אחד נכשל באזור Cloud, מאמתים אחרים באותו אזור ימשיכו לעבד בקשות בצורה חלקה.

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

מאפייני ביצוע העסקה

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

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

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

    למידע נוסף, עיינו בדף העזרה של SubmitTransactionRequest.

זמן אחזור, דגימה ואסטרטגיה של ניסיון חוזר

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

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

  • אם סטטוס העסקה הוא עדיין PENDING, צריך לאחזר את הסטטוס שוב באמצעות אסטרטגיית השהיה מעריכית לפני ניסיון חוזר (exponential backoff). לדוגמה, שאילתה במרווחים של 3 שניות, 9 שניות, 27 שניות ו-60 שניות.

  • אם QueryTransactionState מחזיר את הערך NOT_FOUND, שולחים מחדש את העסקה.

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

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

פרוטוקול זמן קצוב לתפוגה

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

  1. בוחרים נקודת קצה אחרת באזור אחר ברשת.
  2. שולחים מחדש את אותו מטען ייעודי (payload) חתום של העסקה.
  3. כדי לדווח על הבעיה, לוחצים על הכפתור "שליחת משוב" בחלק העליון של הדף הזה, והצוות של Universal Ledger יבדוק אותה.

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

עקביות ברשת

  • עסקאות סופיות: אחרי שמאמת אחד מדווח על עסקה כסופית, כל המאמתים האחרים באותה רשת צפויים לעבד את העסקה בסופו של דבר ולשחזר בדיוק את אותן תוצאות. אם שולחים QueryAccountRequest באמצעות מזהה הסבב שבו העסקה הושלמה, כפי שמופיע ב-TransactionCertificate, מתקבלות תוצאות זהות בכל המאמתים המסונכרנים.

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

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

תחומי האחריות של הלקוח וטיפול בשגיאות

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

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

המאמרים הבאים