Package google.rpc

אינדקס

קוד

קודי השגיאה הקנוניים של ממשקי ה-API של gRPC.

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

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

לא שגיאה, מוחזרת כשהפעולה מצליחה.

מיפוי HTTP: ‏ ‎200 OK

CANCELLED

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

מיפוי HTTP: ‏ 499 Client Closed Request

UNKNOWN

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

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

INVALID_ARGUMENT

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

מיפוי HTTP: ‏ 400 Bad Request

DEADLINE_EXCEEDED

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

מיפוי HTTP: ‏504 הזמן שהוקצב לשער חלף

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 אם הלקוח צריך לנסות שוב ברמה גבוהה יותר. לדוגמה, כשפעולת test-and-set שצוינה על ידי הלקוח נכשלת, מה שמציין שהלקוח צריך להפעיל מחדש רצף של read-modify-write. (ג) להשתמש ב-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 Service Unavailable

DATA_LOSS

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

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

סטטוס

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

מידע נוסף על מודל השגיאות הזה ועל אופן העבודה איתו זמין במדריך לעיצוב API.

שדות
code

int32

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

message

string

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

details[]

Any

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