Package google.rpc

אינדקס

קוד

קודי השגיאה הקנוניים לממשקי 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.