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
הרשאות IAM

נדרשת ההרשאה הבאה ב-IAM במשאב name:

  • routeoptimization.operations.get

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

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, המערכת תשתמש במועד הקצר יותר.