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

ניתן למצוא מידע נוסף כאן: Authentication Overview.
DeleteOperation

rpc DeleteOperation(DeleteOperationRequest) returns (Empty)

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

היקפי הרשאות

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

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

ניתן למצוא מידע נוסף כאן: Authentication Overview.
GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

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

היקפי הרשאות

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

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

ניתן למצוא מידע נוסף כאן: Authentication Overview.
ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

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

היקפי הרשאות

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

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

ניתן למצוא מידע נוסף כאן: Authentication Overview.
WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation)

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

היקפי הרשאות

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

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

ניתן למצוא מידע נוסף כאן: 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

התגובה הרגילה והמוצלחת של הפעולה. אם ה-method המקורית לא מחזירה נתונים כשהיא מצליחה, כמו Delete, התשובה היא google.protobuf.Empty. אם ה-method המקורית היא Get/Create/Update סטנדרטית, התגובה צריכה להיות המשאב. בשיטות אחרות, התגובה צריכה להיות מהסוג XxxResponse, כאשר Xxx הוא שם השיטה המקורי. לדוגמה, אם שם ה-method המקורי הוא TakeSnapshot(), סוג התגובה שמוסק הוא TakeSnapshotResponse.

WaitOperationRequest

הודעת הבקשה של Operations.WaitOperation.

שדות
name

string

שם משאב הפעולה שצריך להמתין לו.
timeout

Duration

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