Package google.rpc

אינדקס

• Code (enum)
• ‫Status (הודעה)

קוד

קודי השגיאה הקנוניים של 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 מכילה שלושה חלקי נתונים: קוד שגיאה, הודעת שגיאה ופרטי שגיאה.

מידע נוסף על מודל השגיאות הזה ועל אופן השימוש בו זמין ב-API Design Guide.

שדות
code	int32 קוד הסטטוס, שצריך להיות ערך enum של google.rpc.Code.
message	string הודעת שגיאה שמוצגת למפתחים, שצריכה להיות באנגלית. כל הודעת שגיאה שמוצגת למשתמש צריכה להיות מותאמת לשפה המקומית ולהישלח בשדה google.rpc.Status.details, או להיות מותאמת לשפה המקומית על ידי הלקוח.
details[]	Any רשימה של הודעות שכוללות את פרטי השגיאה. יש קבוצה משותפת של סוגי הודעות לשימוש בממשקי API.