Package google.longrunning

אינדקס

פעולות

ניהול פעולות ממושכות באמצעות שירות 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
DeleteOperation

rpc DeleteOperation(DeleteOperationRequest) returns (Empty)

מוחק פעולה ממושכת. השיטה הזו מציינת שהלקוח לא מעוניין יותר בתוצאת הפעולה. אי אפשר לבטל את הפעולה. אם השרת לא תומך בשיטה הזו, הוא מחזיר google.rpc.Code.UNIMPLEMENTED.

היקפי הרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

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

היקפי הרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

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

היקפי הרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation)

בהמתנה עד שהפעולה הממושכת שצוינה תסתיים או תגיע לכל היותר הזמן הקצוב לתפוגה שהוגדר, והחזרת המצב האחרון. אם הפעולה כבר בוצעה, המצב העדכני ביותר מוחזר באופן מיידי. אם הזמן הקצוב לתפוגה שצוין גדול מהזמן הקצוב לתפוגה שמוגדר כברירת מחדל ל-HTTP/RPC, ייעשה שימוש בזמן הקצוב לתפוגה של HTTP/RPC. אם השרת לא תומך בשיטה זו, הוא מחזיר google.rpc.Code.UNIMPLEMENTED. שימו לב: השיטה הזו היא על בסיס התוצאה הטובה ביותר. היא יכולה להחזיר את המצב העדכני לפני הזמן הקצוב לתפוגה שצוין (כולל באופן מיידי). כלומר, גם תגובה מיידית לא מבטיחה שהפעולה תתבצע.

היקפי הרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/cloud-platform

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

האסימון הרגיל של דף הרשימה.

ListOperationsResponse

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

שדות
operations[]

Operation

רשימה של פעולות שתואמות למסנן שצוין בבקשה.
next_page_token

string

האסימון הסטנדרטי 'רשימה של הדף הבא'.

פעולה

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