Package google.rpc

אינדקס

קוד

קודי השגיאה הקנוניים של gRPC APIs.

לפעמים יכולים להיות כמה קודי שגיאה. השירותים צריכים להחזיר את קוד השגיאה הספציפי ביותר שרלוונטי. לדוגמה, אם שני הקודים חלים, עדיף להשתמש ב-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 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 ביט תתבקש לקרוא נתונים בהיסט שלא נמצא בטווח [0,2^32-1], היא תיצור INVALID_ARGUMENT, אבל אם היא תתבקש לקרוא נתונים בהיסט שגדול מגודל הקובץ הנוכחי, היא תיצור 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 שגיאת שרת פנימית

סטטוס

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

  • קל לשימוש ולהבנה עבור רוב המשתמשים
  • גמיש מספיק כדי לענות על צרכים בלתי צפויים

סקירה כללית

ההודעה Status מכילה שלושה סוגי נתונים: קוד שגיאה, הודעת שגיאה ופרטי שגיאה. קוד השגיאה צריך להיות ערך enum של google.rpc.Code, אבל יכול להיות שהוא יקבל קודי שגיאה נוספים אם יהיה צורך. הודעת השגיאה צריכה להיות הודעה באנגלית שמיועדת למפתחים, ועוזרת להם להבין את השגיאה ולפתור אותה. אם צריך להציג למשתמש הודעת שגיאה בשפה מקומית, צריך להוסיף את ההודעה המתורגמת לפרטי השגיאה או לתרגם אותה בלקוח. פרטי השגיאה האופציונליים עשויים להכיל מידע שרירותי על השגיאה. יש קבוצה מוגדרת מראש של סוגי פרטי שגיאה בחבילה google.rpc שאפשר להשתמש בהם לתנאי שגיאה נפוצים.

מיפוי שפות

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

שימושים אחרים

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

דוגמאות לשימוש במודל השגיאות הזה:

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

  • שגיאות בתהליך העבודה. תהליך עבודה טיפוסי כולל כמה שלבים. בכל שלב יכולה להופיע Status הודעה לדיווח על שגיאות.

  • פעולות באצווה. אם לקוח משתמש ב-Batch request ובתגובת אצווה, צריך להשתמש בהודעה Status ישירות בתוך תגובת האצווה, אחת לכל תגובת משנה של שגיאה.

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

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

שדות
code

int32

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

message

string

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

details[]

Any

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