Package google.rpc

אינדקס

• Code (טיפוסים בני מנייה)
• Status (מֶסֶר)

קוד

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

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

טיפוסים בני מנייה (enums)
OK	לא שגיאה. הוחזרה בהצלחה. מיפוי HTTP: 200 OK
CANCELLED	הפעולה בוטלה, בדרך כלל על ידי המתקשר. מיפוי HTTP: בקשה סגורה של לקוח 499
UNKNOWN	שגיאה לא ידועה. לדוגמה, ייתכן שהשגיאה הזו תוחזר כאשר ערך Status שהתקבל ממרחב כתובות אחר שייך למרחב שגיאות שאינו ידוע במרחב הכתובות הזה. כמו כן, ניתן להמיר לשגיאה הזו שגיאות שנוצרו על ידי ממשקי API שלא מחזירים מספיק מידע על שגיאות. מיפוי HTTP: שגיאת שרת פנימית 500
INVALID_ARGUMENT	הלקוח ציין ארגומנט לא חוקי. לתשומת ליבך, המספר הזה שונה מהערך FAILED_PRECONDITION. INVALID_ARGUMENT מציין ארגומנטים בעייתיים ללא קשר למצב המערכת (למשל, שם קובץ שגוי). מיפוי HTTP: בקשה לא תקינה 400
DEADLINE_EXCEEDED	המועד האחרון חלף לפני שהפעולה הסתיימה. לגבי פעולות שמשנות את מצב המערכת, ייתכן שהשגיאה הזו תוחזר גם אם הפעולה הסתיימה בהצלחה. לדוגמה, ייתכן שתגובה מוצלחת מהשרת תתעכב מספיק זמן עד שהמועד האחרון יפוג. מיפוי HTTP: הזמן הקצוב לתפוגה של שער 504
NOT_FOUND	חלק מהישות המבוקשת (למשל קובץ או ספרייה) לא נמצאה. הערה למפתחי שרתים: אם בקשה מסוימת נדחית עבור קבוצה שלמה של משתמשים, למשל השקה הדרגתית של תכונה או רשימת היתרים בלתי מתועדת, ניתן להשתמש ב-NOT_FOUND. אם בקשה נדחית ממשתמשים מסוימים בקטגוריה של משתמשים, למשל בקרת גישה מבוססת-משתמש, יש להשתמש ב-PERMISSION_DENIED. מיפוי HTTP: השגיאה 404 לא נמצא
ALREADY_EXISTS	הישות שהלקוח ניסה ליצור (למשל, קובץ או ספרייה) כבר קיימת. מיפוי HTTP: התנגשות 409
PERMISSION_DENIED	למבצע הקריאה החוזרת אין הרשאה לבצע את הפעולה שצוינה. אין להשתמש ב-PERMISSION_DENIED עבור דחיות שנגרמו עקב מיצוי של משאב כלשהו (במקום זאת, יש להשתמש ב-RESOURCE_EXHAUSTED לשגיאות האלה). אין להשתמש ב-PERMISSION_DENIED אם לא ניתן לזהות את המתקשר (יש להשתמש במקום זאת ב-UNAUTHENTICATED עבור שגיאות אלה). קוד השגיאה הזה לא מרמז שהבקשה תקינה או שהישות המבוקשת קיימת או עומדת בתנאים מקדימים אחרים. מיפוי HTTP: 403 אסור
UNAUTHENTICATED	לבקשה אין פרטי כניסה חוקיים לאימות עבור הפעולה. מיפוי HTTP: 401 לא מורשה
RESOURCE_EXHAUSTED	חלק מהמשאבים נוצלו במלואו, ייתכן שמכסת המשתמש התמלאה, או שכל מערכת הקבצים לא תנוצל במלואה. מיפוי HTTP: 429 יותר מדי בקשות
FAILED_PRECONDITION	הפעולה נדחתה כי המערכת לא נמצאת במצב הנדרש לביצוע הפעולה. לדוגמה, הספרייה שיש למחוק אינה ריקה, פעולת rmdir חלה על ספרייה שאינה וכן הלאה. הטמעי שירותים יכולים להשתמש בהנחיות הבאות כדי להחליט בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE: (א) להשתמש ב-UNAVAILABLE אם הלקוח יכול לנסות שוב רק את הקריאה שנכשלה. (ב) יש להשתמש בפונקציה ABORTED אם הלקוח צריך לנסות שוב ברמה גבוהה יותר. לדוגמה, כאשר בדיקה והגדרה שהוגדרה על ידי הלקוח נכשלת, המשמעות היא שהלקוח צריך להפעיל מחדש רצף של קריאה-שינוי-כתיבה. (ג) יש להשתמש ב-FAILED_PRECONDITION אם הלקוח לא אמור לנסות שוב עד שמצב המערכת יתוקן באופן מפורש. לדוגמה, אם 'rmdir' נכשל כי הספרייה לא ריקה, צריך להחזיר את FAILED_PRECONDITION כי הלקוח לא צריך לנסות שוב אלא אם הקבצים נמחקו מהספרייה. מיפוי HTTP: בקשה לא תקינה 400
ABORTED	הפעולה בוטלה, בדרך כלל עקב בעיה בו-זמנית, כמו כשל בבדיקת רצף או ביטול עסקה. אפשר לעיין בהנחיות שלמעלה כדי להחליט בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE. מיפוי HTTP: התנגשות 409
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
UNIMPLEMENTED	הפעולה לא ממומשת או שאינה נתמכת או מופעלת בשירות הזה. מיפוי HTTP: 501 לא יושם
INTERNAL	שגיאות פנימיות. פירוש הדבר הוא שחלק מהמשתנים שצפויים על ידי המערכת הבסיסית אינם תקינים. קוד השגיאה שמור לשגיאות חמורות. מיפוי HTTP: שגיאת שרת פנימית 500
UNAVAILABLE	השירות הזה לא זמין כרגע. סביר להניח שמצב זה הוא זמני, שניתן לתקן אותו על ידי ניסיון חוזר עם השהיה לאחור. שימו לב שלא תמיד כדאי לנסות שוב פעולות שאינן זהות. אפשר לעיין בהנחיות שלמעלה כדי להחליט בין FAILED_PRECONDITION, ABORTED ו-UNAVAILABLE. מיפוי HTTP: שירות 503 לא זמין
DATA_LOSS	פגיעה בנתונים או אובדן נתונים שלא ניתן לשחזר. מיפוי HTTP: שגיאת שרת פנימית 500

סטטוס

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

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

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