במדריך הזה מפורטות המלצות שיעזרו לכם לוודא שהטמעות של לקוחות Universal Ledger יפעלו באינטראקציה עם רשת בצורה מאובטחת ואמינה. בקישורים הבאים תוכלו ללמוד איך:
- שימוש בטופולוגיה של הרשת כדי להשיג זמינות גבוהה.
- שליחת טרנזקציות והבנת תוצאות ההרצה.
- מיישמים אסטרטגיות של שליחת בקשות, פסק זמן וניסיונות חוזרים.
טופולוגיית רשת וזמינות גבוהה
רשת Universal Ledger מורכבת ממספר מאמתים שמפוזרים בין כמה תחומים ואזורים, וכך מבטיחים זמינות גבוהה לרשת כולה.
כשלים באזור: אם מאמת אחד נכשל באזור בענן, מאמתים אחרים באותו אזור ימשיכו לעבד בקשות בצורה חלקה.
הפסקות זמניות באזורים: אם אזור שלם הופך ללא זמין, מאמתים באזורים אחרים ממשיכים לפעול. כדי להמשיך לשלוח עסקאות, הלקוח יכול לחזור אחורה ולנסות לשלוח מחדש עסקאות דרך נקודת קצה אחרת.
מאפייני ביצוע העסקה
ביצוע אטומי: העסקאות מצליחות במלואן או נכשלות במלואן. לא מתבצעת אף פעם פעולה חלקית של עסקה, כמו העברה רק של חלק מהכספים המבוקשים בגלל יתרה לא מספקת. זה כולל שרשראות של עסקאות, שמאפשרות לכם לשלב כמה עסקאות שרירותיות ברצף אטומי אחד.
אין ניסיונות חוזרים אוטומטיים: הרשת מנסה לבצע עסקה שנשלחה בדיוק פעם אחת. אם הביצוע נכשל, הפנקס לא מוסיף את העסקה לתור או מנסה לבצע אותה מחדש באופן אוטומטי.
שליחה חוזרת אידמפוטנטית: כל עסקה שנשלחת יוצרת מזהה עסקה ייחודי על סמך המטען הייעודי (payload) הסדרתי המדויק שלה (כולל מספר רצף והשולח). שליחה של אותו מטען ייעודי (payload) בדיוק כמה פעמים יוצרת את אותו מזהה עסקה. הספר מבטיח שעסקה תתבצע לכל היותר פעם אחת, ולכן אפשר לשלוח מחדש את אותו מטען ייעודי (payload) של עסקה לנקודת קצה אחרת אם אחת מהן לא זמינה.
פרטים נוספים זמינים בדף ההפניה
SubmitTransactionRequest.
זמן אחזור, סקר ושיטת ניסיון חוזר
כששולחים עסקה, כלי האימות מבצע קודם בדיקה מהירה כדי לוודא שהחתימות ומספרי הרצף שלה תקינים. אם הפעולה תצליח, Universal Ledger API ישיב מיד עם SubmitTransactionResponse, כולל מזהה העסקה שהוקצה לה.
רוב העסקאות מסתיימות תוך 3 שניות. כדי לבדוק את סטטוס העסקה, צריך להשתמש בשיטה QueryTransactionState באמצעות מזהה העסקה שסופק.
אם סטטוס העסקה עדיין
PENDING, צריך לאחזר את הסטטוס שוב באמצעות אסטרטגיית נסיגה אקספוננציאלית. לדוגמה, שאילתה במרווחי זמן של 3 שניות, 9 שניות, 27 שניות ו-60 שניות.אם הפונקציה
QueryTransactionStateמחזירהNOT_FOUND, צריך לשלוח מחדש את העסקה.
אחרי ניסיון עסקה עם סטטוס FINALIZED, התשובה תכלול גם את TransactionCertificate עם פרטים שונים כמו:
- מזהה הסיבוב שבו העסקה הסתיימה.
- סטטוס ההרצה (OK או failed).
- אירועי עסקאות, כולל כל הפלט של העסקאות.
פרוטוקול של זמן קצוב לתפוגה
במקרה הלא סביר שעסקה תישאר במצב PENDING או NOT_FOUND אחרי 60 שניות, אפשר להניח שהכלי לאימות שמשרת את הבקשות שלכם לא מצליח לעמוד בקצב של כלי אימות אחרים ברשת. מבצעים את השלבים הבאים:
- בוחרים נקודת קצה אחרת באזור רשת אחר.
- שולחים מחדש את מטען הייעודי (payload) של העסקה החתומה בדיוק כפי שהוא.
- כדי לדווח על הבעיה, אפשר לשלוח אימייל לכתובת gcul-help@google.com כדי שהצוות של Universal Ledger יבדוק אותה.
כשבודקים את סטטוס העסקה, יכול להיות שהתגובה תכלול כמה הודעות TransactionAttempt אם שלחתם את אותו מטען ייעודי (payload) כמה פעמים. לכל היותר ניסיון אחד יסתיים עם סטטוס עסקה OK, שמופיע ב-TransactionEffects, בעוד שניסיונות אחרים יהיו בהמתנה או שהסטטוס שלהם יהיה 'נכשל'. זהו התנהגות צפויה. הפנקס ביצע בהצלחה את אחת מהעברות העסקאות ודחה בצורה נכונה את ההעברות הכפולות, או ידחה אותן בסופו של דבר.
עקביות ברשת
עסקאות סופיות: אחרי שאמצעי אימות אחד מדווח על עסקה כסופית, כל שאר אמצעי האימות באותה רשת צפויים לעבד את העסקה בסופו של דבר ולשחזר בדיוק את אותן תוצאות. שליחת
QueryAccountRequestבאמצעות מזהה הסיבוב שבו העסקה הסתיימה, כפי שמופיע בTransactionCertificate, מניבה תוצאות זהות בכל מאמתים מסונכרנים.עסקאות שלא הושלמו: מכיוון שהעסקאות מועברות ברשת באופן אסינכרוני, יכול להיות שמאמתים שונים ידווחו על עסקה מסוימת כעסקה שהושלמה או כעסקה שלא הושלמה.
מאמת שמתאושש מהפסקת חשמל או שחווה השהיה בסנכרון עשוי לדווח באופן זמני על עסקה סופית כ-
PENDINGאו כ-NOT_FOUND. סטטוס העסקה יתעדכן אחרי שהמאמת יסיים את הבדיקה.
תחומי האחריות של הלקוח וטיפול בשגיאות
מעקב אחר עסקאות: אפליקציות לקוח צריכות לעקוב אחרי הסטטוס של כל העסקאות שנשלחו עד שהן מסתיימות.
טיפול בשגיאות: אם עסקה נכשלת, צריך לאחזר ולבדוק את פרטי הכשל שכלולים ב-
TransactionCertificateכדי להפעיל את התיקון המתאים ברמת העסק.
המאמרים הבאים
- איך שולחים בקשות RPC ל-Universal Ledger API
- מידע נוסף זמין במאמר בנושא הפניית Universal Ledger API.