Package google.longrunning

אינדקס

• ‫Operations (ממשק)
• ‫CancelOperationRequest (הודעה)
• ‫DeleteOperationRequest (הודעה)
• ‫GetOperationRequest (הודעה)
• ‫ListOperationsRequest (הודעה)
• ‫ListOperationsResponse (הודעה)
• ‫Operation (הודעה)
• ‫WaitOperationRequest (הודעה)

תפעול

ניהול פעולות ממושכות באמצעות שירות API.

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

CancelOperation

rpc CancelOperation(CancelOperationRequest) returns (Empty) מתחיל ביטול אסינכרוני של פעולה ממושכת. השרת עושה כל מאמץ לבטל את הפעולה, אבל אין ערובה לכך שהביטול יצליח. אם השרת לא תומך בשיטה הזו, הוא מחזיר google.rpc.Code.UNIMPLEMENTED. לקוחות יכולים להשתמש ב-Operations.GetOperation או בשיטות אחרות כדי לבדוק אם הביטול הצליח או אם הפעולה הושלמה למרות הביטול. אם הביטול מצליח, הפעולה לא נמחקת. במקום זאת, היא הופכת לפעולה עם ערך Operation.error ועם google.rpc.Status.code של 1, שמתאים ל-Code.CANCELLED. היקפי הרשאות נדרש אחד מהיקפי ההרשאות הבאים של OAuth: https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/notebooks ניתן למצוא מידע נוסף כאן: Authentication Overview.

DeleteOperation

rpc DeleteOperation(DeleteOperationRequest) returns (Empty) מחיקת פעולה ממושכת. השיטה הזו מציינת שהלקוח כבר לא מתעניין בתוצאת הפעולה. הפעולה לא תבוטל. אם השרת לא תומך בשיטה הזו, הוא מחזיר google.rpc.Code.UNIMPLEMENTED. היקפי הרשאות נדרש אחד מהיקפי ההרשאות הבאים של OAuth: https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/notebooks ניתן למצוא מידע נוסף כאן: Authentication Overview.

GetOperation
rpc GetOperation(GetOperationRequest) returns (Operation) מקבל את המצב העדכני של פעולה ממושכת. לקוחות יכולים להשתמש בשיטה הזו כדי לדגום את תוצאת הפעולה במרווחי זמן לפי ההמלצות של שירות ה-API. היקפי הרשאות נדרש אחד מהיקפי ההרשאות הבאים של OAuth: https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/notebooks ניתן למצוא מידע נוסף כאן: Authentication Overview.

ListOperations
rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse) רשימת פעולות שתואמות למסנן שצוין בבקשה. אם השרת לא תומך בשיטה הזו, הוא מחזיר UNIMPLEMENTED. היקפי הרשאות נדרש אחד מהיקפי ההרשאות הבאים של OAuth: https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/notebooks ניתן למצוא מידע נוסף כאן: Authentication Overview.

WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation) המתנה עד שהפעולה הממושכת שצוינה תסתיים או עד שיחלוף הזמן הקצוב לתפוגה שצוין, והחזרת הסטטוס העדכני. אם הפעולה כבר בוצעה, המצב האחרון מוחזר באופן מיידי. אם ערך הזמן הקצוב לתפוגה שצוין גדול יותר מערך ברירת המחדל של הזמן הקצוב לתפוגה של HTTP/RPC, המערכת משתמשת בערך ברירת המחדל של הזמן הקצוב לתפוגה של HTTP/RPC. אם השרת לא תומך בשיטה הזו, הוא מחזיר google.rpc.Code.UNIMPLEMENTED. שימו לב שהשיטה הזו היא על בסיס best-effort. יכול להיות שהיא תחזיר את המצב האחרון לפני פסק הזמן שצוין (כולל באופן מיידי), כלומר גם תגובה מיידית לא מבטיחה שהפעולה הסתיימה. היקפי הרשאות נדרש אחד מהיקפי ההרשאות הבאים של OAuth: https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/notebooks ניתן למצוא מידע נוסף כאן: Authentication Overview.

CancelOperationRequest

ההודעה עם הבקשה בשביל Operations.CancelOperation.

שדות
name	string השם של משאב הפעולה שרוצים לבטל.

DeleteOperationRequest

ההודעה עם הבקשה בשביל Operations.DeleteOperation.

שדות
name	string שם משאב הפעולה שרוצים למחוק.

GetOperationRequest

ההודעה עם הבקשה בשביל Operations.GetOperation.

שדות
name	string השם של משאב הפעולה.

ListOperationsRequest

ההודעה עם הבקשה בשביל Operations.ListOperations.

שדות
name	string השם של משאב ההורה של הפעולה.
filter	string מסנן הרשימה הרגיל.
page_size	int32 גודל הדף הסטנדרטי של הרשימה.
page_token	string טוקן הדף של רשימת ברירת המחדל.
return_partial_success	bool כשהערך מוגדר כ-true, פעולות שאפשר להגיע אליהן מוחזרות כרגיל, ופעולות שלא ניתן להגיע אליהן מוחזרות בשדה ListOperationsResponse.unreachable. האפשרות הזו יכולה להיות true רק כשקוראים נתונים מכמה אוספים. לדוגמה, כשמגדירים את parent לערך "projects/example/locations/-". השדה הזה לא נתמך כברירת מחדל, ואם הוא מוגדר, תופיע שגיאה UNIMPLEMENTED, אלא אם צוין אחרת במפורש במסמכי התיעוד הספציפיים לשירות או למוצר.

ListOperationsResponse

הודעת התשובה ל-Operations.ListOperations.

שדות
operations[]	Operation רשימה של פעולות שתואמות למסנן שצוין בבקשה.
next_page_token	string אסימון רגיל של רשימת הדפים הבאים.
unreachable[]	string רשימה לא ממוינת. משאבים שלא ניתן להגיע אליהם. השדה הזה מאוכלס כשהבקשה מגדירה את ListOperationsRequest.return_partial_success וקוראת באוספים. לדוגמה, כשמנסים ליצור רשימה של כל המשאבים בכל המיקומים הנתמכים.

פעולה

המשאב הזה מייצג פעולה ממושכת שמוחזרת מקריאות ל-API ברשת.

שדות
name	string השם שהוקצה על ידי השרת, שהוא ייחודי רק בתוך אותו שירות שהחזיר אותו במקור. אם משתמשים במיפוי ברירת המחדל של HTTP, הערך של name צריך להיות שם משאב שמסתיים ב-operations/{unique_id}.
metadata	Any מטא-נתונים ספציפיים לשירות שמשויכים לפעולה. הוא בדרך כלל מכיל מידע על ההתקדמות ומטא-נתונים נפוצים כמו זמן היצירה. יכול להיות שחלק מהשירותים לא יספקו מטא-נתונים כאלה. בכל שיטה שמחזירה פעולה ממושכת, צריך לתעד את סוג המטא-נתונים, אם יש כאלה.
done	bool אם הערך הוא false, המשמעות היא שהפעולה עדיין מתבצעת. אם הערך הוא true, הפעולה הושלמה ואפשר להשתמש בערך error או response.
שדה איחוד result. תוצאת הפעולה, שיכולה להיות error או response תקין. אם done == false, אף אחד מהערכים error או response לא מוגדר. אם done == true, אפשר להגדיר בדיוק אחד מהערכים error או response. יכול להיות שחלק מהשירותים לא יספקו את התוצאה. הערך result יכול להיות רק אחד מהבאים:
error	Status תוצאת השגיאה של הפעולה במקרה של כשל או ביטול.
response	Any התגובה הרגילה והמוצלחת של הפעולה. אם השיטה המקורית לא מחזירה נתונים בהצלחה, כמו Delete, התגובה היא google.protobuf.Empty. אם השיטה המקורית היא Get/Create/Update, התגובה צריכה להיות המשאב. בשיטות אחרות, התשובה צריכה להיות מהסוג XxxResponse, כאשר Xxx הוא שם השיטה המקורי. לדוגמה, אם שם השיטה המקורי הוא TakeSnapshot(), סוג התגובה שמוסק הוא TakeSnapshotResponse.

WaitOperationRequest

ההודעה עם הבקשה בשביל Operations.WaitOperation.

שדות
name	string השם של משאב הפעולה שממתינים לסיום שלו.
timeout	Duration משך הזמן המקסימלי להמתנה לפני פסק זמן. אם משאירים את השדה ריק, ההמתנה תהיה לכל היותר הזמן שמותר לפי פרוטוקול ה-HTTP/RPC הבסיסי. אם מציינים גם תאריך יעד להקשר של RPC, המערכת תשתמש בתאריך הקצר יותר.