דף זה תורגם על ידי Cloud Translation API.

Package google.rpc

אינדקס

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

קוד

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

code

int32

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

message

string

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

details[]

Any

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