ErrorSummary

סיכום שגיאות לפי קוד שגיאה, בתוספת ספירה ודוגמאות של ערכי יומן שגיאות.

ייצוג JSON 
{
  "errorCode": enum (Code),
  "errorCount": string,
  "errorLogEntries": [
    {
      object (ErrorLogEntry)
    }
  ]
}
שדות
errorCode

enum (Code)

חובה. קוד השגיאה הקנוני.
errorCount

string (int64 format)

חובה. מספר שגיאות שנתקלו בהן לכל errorCode.
errorLogEntries[]

object (ErrorLogEntry)

חובה. יומני שגיאות לדוגמה.

קוד

קודי השגיאה הקנוניים עבור ממשקי API של gRPC.

לעיתים עשויים לחול מספר קודי שגיאה. השירותים צריכים להחזיר את קוד השגיאה הספציפי ביותר שחל. לדוגמה, העדיפו את OUT_OF_RANGE על פני FAILED_PRECONDITION אם שני הקודים רלוונטיים. באופן דומה, עדיף NOT_FOUND או ALREADY_EXISTS על פני FAILED_PRECONDITION.

טיפוסים בני מנייה (enum)
OK

לא שגיאה; הוחזר בהצלחה.

מיפוי HTTP: 200 בסדר
CANCELLED

הפעולה בוטלה, בדרך כלל על ידי המתקשר.

מיפוי HTTP: בקשת סגירה של לקוח 499
UNKNOWN

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

מיפוי HTTP: ‏ 500 שגיאת שרת פנימית
INVALID_ARGUMENT

הלקוח ציין ארגומנט לא חוקי. שימו לב שהמאפיין הזה שונה ממאפיין FAILED_PRECONDITION. ‫INVALID_ARGUMENT מציין ארגומנטים בעייתיים ללא קשר למצב המערכת (למשל, שם קובץ לא תקין).

מיפוי HTTP: ‏ 400 Bad Request
DEADLINE_EXCEEDED

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

מיפוי HTTP: ‏ 504 Gateway Timeout
NOT_FOUND

לא נמצאה ישות מבוקשת (לדוגמה, קובץ או ספרייה).

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

מיפוי HTTP: ‏ 404 לא נמצא
ALREADY_EXISTS

הישות שהלקוח ניסה ליצור (למשל, קובץ או ספרייה) כבר קיימת.

מיפוי HTTP: ‏ ‎409 Conflict
PERMISSION_DENIED

למתקשר אין הרשאה לבצע את הפעולה שצוינה. אסור להשתמש בערך PERMISSION_DENIED לדחיות שנגרמות בגלל מיצוי של משאב מסוים (במקום זאת צריך להשתמש בערך RESOURCE_EXHAUSTED לשגיאות האלה). אסור להשתמש ב-PERMISSION_DENIED אם אי אפשר לזהות את המתקשר (במקום זאת, צריך להשתמש ב-UNAUTHENTICATED בשגיאות האלה). קוד השגיאה הזה לא מרמז שהבקשה תקפה או שהישויות המבוקשות קיימות או עומדות בתנאים מוקדמים אחרים.

מיפוי HTTP: ‏ 403 Forbidden
UNAUTHENTICATED

בבקשה לא צוינו פרטי כניסה תקפים לאימות לצורך ביצוע הפעולה.

מיפוי HTTP: ‏ 401 Unauthorized (אין הרשאה)
RESOURCE_EXHAUSTED

אזל המשאב, אולי מכסת משתמש או אולי אין יותר מקום במערכת הקבצים.

מיפוי HTTP: ‏ 429 Too Many Requests
FAILED_PRECONDITION

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

מיישמי שירות יכולים להשתמש בהנחיות הבאות כדי להחליט בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE: (א) השתמשו ב-UNAVAILABLE אם הלקוח יכול לנסות שוב רק את הקריאה שנכשלה. ‫(ב) משתמשים בערך ABORTED אם הלקוח צריך לנסות שוב ברמה גבוהה יותר. לדוגמה, כשבדיקה והגדרה שצוינו על ידי הלקוח נכשלות, מה שמצביע על כך שהלקוח צריך להפעיל מחדש רצף של קריאה, שינוי וכתיבה. ‫(c) משתמשים ב-FAILED_PRECONDITION אם הלקוח לא צריך לנסות שוב עד שמצב המערכת תוקן באופן מפורש. לדוגמה, אם הפקודה rmdir נכשלת כי הספרייה לא ריקה, צריך להחזיר את FAILED_PRECONDITION כי הלקוח לא אמור לנסות שוב אלא אם הקבצים נמחקים מהספרייה.

מיפוי HTTP: ‏ 400 Bad Request
ABORTED

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

בהנחיות שלמעלה מוסבר איך קובעים מהו השיוך המתאים ביותר מבין FAILED_PRECONDITION,‏ ABORTED ו-UNAVAILABLE.

מיפוי HTTP: ‏ ‎409 Conflict
OUT_OF_RANGE

הניסיון לבצע את הפעולה היה אחרי הטווח התקף. לדוגמה, חיפוש או קריאה מעבר לסוף הקובץ.

בניגוד לשגיאה INVALID_ARGUMENT, השגיאה הזו מצביעה על בעיה שאולי תיפתר אם מצב המערכת ישתנה. לדוגמה, מערכת קבצים של 32 סיביות תיצור INVALID_ARGUMENT אם תתבקש לקרוא בהיסט שאינו בטווח [0,2^32-1], אך היא תיצור OUT_OF_RANGE אם תתבקש לקרוא מהיסט מעבר לגודל הקובץ הנוכחי.

יש חפיפה לא קטנה בין FAILED_PRECONDITION לבין OUT_OF_RANGE. מומלץ להשתמש ב-OUT_OF_RANGE (השגיאה הספציפית יותר) כשהיא רלוונטית, כדי שמשתמשים שמתקשרים למרחב יוכלו לחפש בקלות שגיאת OUT_OF_RANGE ולדעת שהם סיימו.

מיפוי HTTP: ‏ 400 Bad Request
UNIMPLEMENTED

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

מיפוי HTTP: ‏ ‎501 Not Implemented
INTERNAL

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

מיפוי HTTP: ‏ 500 שגיאת שרת פנימית
UNAVAILABLE

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

בהנחיות שלמעלה מוסבר איך קובעים מהו השיוך המתאים ביותר מבין FAILED_PRECONDITION,‏ ABORTED ו-UNAVAILABLE.

מיפוי HTTP: שירות 503 אינו זמין
DATA_LOSS

אובדן או פגיעה בנתונים בלתי ניתנים לשחזור.

מיפוי HTTP: ‏ 500 שגיאת שרת פנימית

ErrorLogEntry

ערך המתאר שגיאה שאירעה.

ייצוג JSON 
{
  "objectUri": string,
  "errorDetails": [
    string
  ]
}
שדות
objectUri

string

חובה. פלט בלבד. כתובת URL של אובייקט, לדוגמה, gs://my_bucket/object.txt
errorDetails[]

string

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