יש שיטות (methods) של Google Cloud API שפעולתן נמשכת זמן רב.
במקום לחסום עד לסיום העבודה, השיטות האלה מחזירות משאב Operation שמייצג פעולה שמתבצעת, כדי שהאפליקציה תוכל לדגום את הסטטוס ואת התוצאה הסופית שלה.
ספריות הלקוח ב-Cloud ל-Rust מספקות כלי עזר לעבודה עם הפעולות הממושכות האלה (LRO). במאמר הזה מוסבר איך להתחיל LRO, לדגום באופן אוטומטי עד לסיום, לבדוק עדכוני התקדמות ביניים ולדגום באופן ידני.
לפני שמתחילים
במאמר הזה נשתמש ב-Cloud Storage כדי להציג דוגמאות קונקרטיות לקוד, אבל אותם מושגים רלוונטיים לכל שירות של Google Cloud שמשתמש ב-LRO.
לפני שמריצים את הקוד במסמך הזה, צריך להשלים את הדרישות המוקדמות הבאות:
- יוצרים או בוחרים פרויקט ב-Google Cloud שהחיוב מופעל בו.
- כדי להגדיר את סביבת הפיתוח ואת פרטי הכניסה, פועלים לפי ההוראות במאמר תחילת העבודה עם Rust.
- יוצרים קטגוריה של Cloud Storage עם מרחב שמות היררכי, ויוצרים תיקיית מקור כדי לשנות את השם שלה.
- מקצים לחשבון המשתמש תפקיד בממשק לניהול הזהויות והרשאות הגישה (IAM) עם הרשאה לניהול תיקיות, כמו אדמין של Storage (
roles/storage.admin).
יחסי תלות
מוסיפים את ספריית הלקוח ואת ה-crate של LRO לקובץ Cargo.toml:
cargo add google-cloud-storage google-cloud-lro google-cloud-longrunning anyhow
מוסיפים את tokio להפעלה אסינכרונית ולטיימרים:
cargo add tokio --features full
התחלת פעולה ממושכת
בדוגמאות שבמסמך הזה מתבצעת קריאה לפעולה rename folder ב-Cloud Storage, שמחזירה LRO. כדי להפעיל LRO ישירות ולקבל את המשאב הראשוני של Operation, מבצעים את הפעולות הבאות:
מוסיפים הצהרות
useכדי לקצר את נתיבי הסוגים:מגדירים פונקציית
asyncשמקבלת את מזהה הקטגוריה, מזהה תיקיית המקור ומזהה תיקיית היעד:מאתחלים את הלקוח של
StorageControl:יוצרים את הכלי ליצירת בקשות של
rename_folder:שולחים את הבקשה וממתינים למשאב
Operationהראשוני, שמייצג את הפעולה ברקע:
אחרי שמתחילים את הפעולה, ממתינים שהיא תסתיים כדי לאחזר את התוצאה הסופית שלה.
דגימה אוטומטית של פעולה ממושכת
ברוב התרחישים לדוגמה, משתמשים ב-method until_done של המאפיין Poller במקום לקרוא ישירות ל-send. ה-poller מפעיל את ה-LRO, מבצע דגימה לפי מדיניות ההשהיה לפני ניסיון חוזר (backoff) והטיפול בשגיאות של הלקוח, ומחזיר את התשובה הסופית:
הוספת המאפיין
Pollerלהיקף:מאתחלים לקוח
StorageControlומגדירים את הכלי ליצירת בקשותrename_folder:מפעילים את
pollerואתuntil_doneבכלי ליצירת בקשות כדי להמתין להשלמה ולהדפיס את התוצאה:
קוד מלא של סקר אוטומטי
הפונקציה הבאה מציגה את הדוגמה המלאה של דגימה אוטומטית:
דגימה של פעולה ממושכת עם תוצאות ביניים
השיטה until_done מחזירה רק את התוצאה הסופית ומשמיטה עדכוני מטא-נתונים זמניים. אם האפליקציה צריכה עדכוני התקדמות בזמן שה-LRO פועל, צריך לקבל פולר עם poller ולקרוא ל-poll בלולאה:
מייבאים את
Pollerו-PollingResult:ממירים את הכלי ליצירת בקשות לכלי דגימה באמצעות
poller:מפעילים את
poller.poll().awaitבלולאה כדי לעבד את המצביםInProgress,PollingErrorו-Completed:
כשמתקשרים ישירות אל poll, הלולאה שולטת בהשהיה בין ניסיונות הסקר. בוחרים השהיה שמתאימה למשך הזמן הצפוי של הפעולה.
קוד מלא לדגימה עם תוצאות ביניים
הפונקציה הבאה מציגה את הלולאה המלאה של poll:
דגימה ידנית של פעולה ממושכת
למרות שהמאפיין Poller מטפל כמעט בכל התרחישים לדוגמה, אפשר גם לדגום Operation באופן ידני באמצעות get_operation:
אחרי הפעלת ה-LRO באמצעות
send, נכנסים ללולאה ובודקים את השדהdone:בודקים את
operation.result. השדהresultהואOptionכי פעולות מסוימות, כמו מחיקות, מסתיימות בלי להחזיר מטען ייעודי (payload). ב-rename_folder, השירות מחזיר משאבFolder:בודקים אם הפעולה הסתיימה עם שגיאה. הווריאנט של השגיאה מכיל הודעת
Status, שבדוגמה הבאה מעוצבת כשגיאה, או שאפשר להמיר אותה לשגיאת לקוח באמצעותError::service:אם הפעולה הצליחה, פורקים את המטען הייעודי (payload) של
Anyלסוג התגובה הצפוי שלFolder:מוסיפים זרוע של תו כללי לחיפוש כי טיפוסי ה-enum בספריות הלקוח של Cloud ל-Rust מסומנים בתור
#[non_exhaustive]:אופציונלי: בזמן ש-
operation.doneהואfalse, פורקים אתoperation.metadataכדי לבדוק את עדכוני ההתקדמות:צריך להמתין לפני ששולחים שוב בקשה. בדוגמה הזו, כדי לקצר, ההשהיה היא למשך 500 אלפיות השנייה. בקוד ייצור, צריך להשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff):
שולחים קריאה אל
get_operationעםoperation.nameכדי לרענן את סטטוס הפעולה:
קוד מלא לדגימה ידנית
הפונקציה הבאה משלבת את כל שלבי הסקר הידני: