REST Resource: operations

משאב: פעולה

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

ייצוג ב-JSON
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
}
שדות
name

string

השם שהוקצה על ידי השרת, שהוא ייחודי רק בתוך אותו שירות שמחזיר אותו במקור. אם משתמשים במיפוי ברירת המחדל של HTTP, הערך של name צריך להיות שם משאב שמסתיים ב-operations/{unique_id}.

metadata

object

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

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף, "@type", מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

done

boolean

אם הערך הוא false, הפעולה עדיין מתבצעת. אם הערך הוא true, הפעולה הושלמה, וזמינה התגובה error או response.

תוצאת הפעולה, שיכולה להיות error או response חוקי. אם done == false, לא מוגדרים error וגם response. אם done == true, אפשר להגדיר רק אחד מהשדות error או response. יכול להיות שחלק מהשירותים לא יספקו את התוצאה. זו רשימה של שדות שמוציאים זה את זה. בתשובה יוגדר לכל היותר אחד מהשדות הבאים:
error

object (Status)

תוצאת השגיאה של הפעולה במקרה של כישלון או ביטול.

response

object

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

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף, "@type", מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

סוף השדות שמוציאים זה את זה.

סטטוס

הסוג Status מגדיר מודל שגיאה לוגי שמתאים לסביבות תכנות שונות, כולל ממשקי API בארכיטקטורת REST וממשקי API ל-RPC. הוא משמש את gRPC. כל הודעת Status מכילה שלושה פריטי נתונים: קוד שגיאה, הודעת שגיאה ופרטי שגיאה.

במדריך לעיצוב API מוסבר בהרחבה על מודל השגיאות הזה ואיך לעבוד איתו.

ייצוג ב-JSON
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
שדות
code

integer

קוד הסטטוס, שצריך להיות ערך enum של google.rpc.Code.

message

string

הודעת שגיאה שמיועדת למפתחים, וצריכה להיות באנגלית. כל הודעת שגיאה שגלויה למשתמשים צריכה להיות מותאמת לשוק המקומי ולהישלח בשדה google.rpc.Status.details, או להיות מותאמת לשוק המקומי על ידי הלקוח.

details[]

object

רשימת הודעות עם פרטי השגיאה. יש קבוצה נפוצה של סוגי הודעות לשימוש בממשקי API.

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף, "@type", מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

Methods

cancel

התחלת ביטול אסינכרוני של פעולה ממושכת.

delete

מחיקה של פעולה ממושכת.

get

מקבלת את המצב האחרון של פעולה ממושכת.

list

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