דף זה תורגם על ידי 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
`NOT_FOUND`	לא נמצאה ישות מבוקשת (למשל קובץ או ספרייה). הערה למפתחי שרתים: אם בקשה מסוימת נדחית עבור קבוצת משתמשים שלמה, כמו השקה הדרגתית של תכונה או רשימת היתרים לא מתועדת, ניתן להשתמש ב-`NOT_FOUND`. אם בקשה מסוימת נדחית עבור חלק מהמשתמשים בכיתה של משתמשים, למשל בקרת גישה מבוססת-משתמשים, חייבים להשתמש ב-`PERMISSION_DENIED`. מיפוי HTTP: 404 לא נמצא
`ALREADY_EXISTS`	הישות שהלקוח ניסה ליצור (למשל, קובץ או ספרייה) כבר קיימת. מיפוי HTTP: התנגשות 409
`PERMISSION_DENIED`	למשתמש ששלח את הקריאה אין הרשאה לבצע את הפעולה שצוינה. אין להשתמש בפונקציה `PERMISSION_DENIED` לדחיות שנגרמו עקב מיצוי של משאב כלשהו (במקום זאת, יש להשתמש ב-`RESOURCE_EXHAUSTED` לשגיאות האלה). אם המתקשר לא מזוהה, אסור להשתמש ב-`PERMISSION_DENIED` (יש להשתמש ב-`UNAUTHENTICATED` במקום בשגיאות האלה). קוד השגיאה הזה לא מרמז על כך שהבקשה חוקית או שהישות המבוקשת קיימת או עומדת בתנאים מוקדמים אחרים. מיפוי HTTP: 403 Forbidden
`UNAUTHENTICATED`	לבקשה אין פרטי כניסה תקפים לאימות הפעולה. מיפוי HTTP: 401 Unauthorized
`RESOURCE_EXHAUSTED`	חלק מהמשאבים אזלו, אולי מכסה לכל משתמש, או אולי אין מספיק מקום במערכת הקבצים כולה. מיפוי HTTP: 429 בקשות רבות מדי
`FAILED_PRECONDITION`	הפעולה נדחתה כי המערכת לא במצב שנדרש לביצוע הפעולה. לדוגמה, הספרייה שרוצים למחוק לא ריקה, פעולת rmdir חלה על ספרייה שאינה ספרייה וכו'. מטמיעי שירותים יכולים להשתמש בהנחיות הבאות כדי להחליט בין `FAILED_PRECONDITION`, `ABORTED` ו-`UNAVAILABLE`: (א) אפשר להשתמש ב-`UNAVAILABLE` אם הלקוח יכול לנסות שוב רק את הקריאה שנכשלה. (ב) אם הלקוח צריך לנסות שוב ברמה גבוהה יותר, צריך להשתמש ב-`ABORTED`. לדוגמה, כשפעולת בדיקה והגדרה בהגדרת הלקוח נכשלת, המשמעות היא שהלקוח צריך להפעיל מחדש רצף של קריאה-שינוי-כתיבה. (ג) צריך להשתמש ב-`FAILED_PRECONDITION` אם הלקוח לא צריך לנסות שוב עד שמצב המערכת יתוקן באופן מפורש. לדוגמה, אם הפרמטר 'rmdir' נכשל כי הספרייה לא ריקה, לכן צריך להחזיר את `FAILED_PRECONDITION` כי הלקוח לא צריך לנסות שוב, אלא אם הקבצים נמחקים מהספרייה. מיפוי HTTP: 400 Bad Request
`ABORTED`	הפעולה בוטלה, בדרך כלל עקב בעיה בו-זמניות (concurrency) כגון כשל בבדיקת רצף או ביטול עסקה. ההנחיות שלמעלה יעזרו לך להחליט בין `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 Bad Request
`UNIMPLEMENTED`	הפעולה לא יושמה או אינה נתמכת/מופעלת בשירות זה. מיפוי HTTP: 501 לא מיושם
`INTERNAL`	שגיאות פנימיות. המשמעות היא שחלק מהמשתנים הקבועים הצפויים על ידי המערכת הבסיסית מנותקים. קוד השגיאה הזה שמור לשגיאות חמורות. מיפוי HTTP: שגיאת שרת פנימית 500
`UNAVAILABLE`	השירות הזה לא זמין כרגע. סביר להניח שמדובר במצב זמני, ואפשר לתקן אותו באמצעות ניסיון חוזר עם השהיה לפני ניסיון חוזר (backoff). שימו לב שלא תמיד בטוח לבצע ניסיון חוזר של פעולות שהן לא אידמפוטנטיות. ההנחיות שלמעלה יעזרו לך להחליט בין `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.