Package google.longrunning

אינדקס

תפעול

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

אם שיטת API מסוימת בדרך כלל לוקחת הרבה זמן להשלמה, אפשר לתכנן אותה כך שתחזיר Operation ללקוח, והלקוח יוכל להשתמש בממשק הזה כדי לקבל את התגובה האמיתית באופן אסינכרוני על ידי דגימה של משאב הפעולה, או להעביר את משאב הפעולה ל-API אחר (כמו Google Cloud 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/cloud-vision

מידע נוסף מופיע במאמר סקירה כללית על אימות.
DeleteOperation

rpc DeleteOperation(DeleteOperationRequest) returns (Empty)

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

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

מידע נוסף מופיע במאמר סקירה כללית על אימות.
GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

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

מידע נוסף מופיע במאמר סקירה כללית על אימות.
ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

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

הערה: הקישור name מאפשר לשירותי API לבטל את הקישור כדי להשתמש בסכימות שונות של שמות משאבים, כמו users/*/operations. כדי לבטל את הקישור, שירותי API יכולים להוסיף קישור כמו "/v1/{name=users/*}/operations" להגדרת השירות שלהם. לצורך תאימות לאחור, שם ברירת המחדל כולל את מזהה אוסף הפעולות, אבל משתמשים שמבטלים את ברירת המחדל צריכים לוודא שהשם המקושר הוא משאב האב, בלי מזהה אוסף הפעולות.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

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

מידע נוסף מופיע במאמר סקירה כללית על אימות.
WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation)

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

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

מידע נוסף מופיע במאמר סקירה כללית על אימות.

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/some/unique/name.

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