Package google.rpc

אינדקס

BadRequest

מתאר הפרות בבקשה של לקוח. סוג השגיאה הזה מתמקד בהיבטים התחביריים של הבקשה.

שדות
field_violations[]

FieldViolation

מתאר את כל ההפרות בבקשת לקוח.

FieldViolation

סוג הודעה שמשמש לתיאור של שדה אחד בבקשה שגויה.

שדות
field

string

נתיב שמוביל לשדה בגוף הבקשה. הערך יהיה רצף של מזהים מופרדים בנקודות שמזהים שדה של מאגר אחסון לפרוטוקולים.

כמה נקודות שכדאי לזכור:

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

בדוגמה הזו, הערך של field ב-proto יכול להיות אחד מהערכים הבאים:

  • ‫full_name בגלל הפרה בערך full_name
  • ‫email_addresses[0].email בשדה email של ההודעה הראשונה email_addresses
  • ‫email_addresses[2].type[1] להפרה בערך השני type במסר השלישי email_addresses.

ב-JSON, אותם ערכים מיוצגים כך:

  • ‫fullName בגלל הפרה בערך fullName
  • ‫emailAddresses[0].email בשדה email של ההודעה הראשונה emailAddresses
  • ‫emailAddresses[2].type[1] להפרה בערך השני type במסר השלישי emailAddresses.
description

string

תיאור של הסיבה לכך שרכיב הבקשה בעייתי.
reason

string

הסיבה לשגיאה ברמת השדה. זהו ערך קבוע שמזהה את הגורם הקרוב לשגיאה ברמת השדה. המזהה צריך להיות ייחודי לסוג של FieldViolation בהיקף של google.rpc.ErrorInfo.domain. האורך המקסימלי הוא 63 תווים, והערך צריך להתאים לביטוי הרגולרי [A-Z][A-Z0-9_]+[A-Z0-9], שמייצג UPPER_SNAKE_CASE.
localized_message

LocalizedMessage

הפונקציה מספקת הודעת שגיאה מותאמת לשפה המקומית עבור שגיאות ברמת השדה, שאפשר להחזיר אותה בבטחה לצרכן ה-API.

קוד

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

הפעולה בוטלה, בדרך כלל בגלל בעיה של בו-זמניות (concurrency), כמו כשל בבדיקת רצף או ביטול טרנזקציה.

בהנחיות שלמעלה מוסבר איך קובעים מהו השיוך המתאים ביותר מבין 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

השירות הזה לא זמין כרגע. הסיבה לכך היא כנראה מצב זמני, שאפשר לתקן אותו על ידי ניסיון חוזר עם השהיה לפני ניסיון חוזר (backoff). חשוב לזכור שלא תמיד בטוח לנסות שוב פעולות שהן לא אידמפוטנטיות.

בהנחיות שלמעלה מוסבר איך קובעים מהו השיוך המתאים ביותר מבין FAILED_PRECONDITION,‏ ABORTED ו-UNAVAILABLE.

מיפוי HTTP: ‏ 503 השירות לא זמין
DATA_LOSS

פגם בנתונים או אובדן נתונים שלא ניתן לשחזר.

מיפוי HTTP: ‏ 500 שגיאת שרת פנימית

ErrorInfo

תיאור הגורם לשגיאה עם פרטים מובְנים.

דוגמה לשגיאה שמתרחשת כשפונים אל API ‏'pubsub.googleapis.com' כשהוא לא מופעל:

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

התשובה הזו מציינת שממשק ה-API של pubsub.googleapis.com לא מופעל.

דוגמה לשגיאה שמוחזרת כשמנסים ליצור מופע Spanner באזור שבו אין מלאי:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
שדות
reason

string

הסיבה לשגיאה. זהו ערך קבוע שמזהה את הסיבה הקרובה לשגיאה. הסיבות לשגיאות הן ייחודיות לדומיין מסוים של שגיאות. האורך המקסימלי הוא 63 תווים, והערך צריך להתאים לביטוי הרגולרי [A-Z][A-Z0-9_]+[A-Z0-9], שמייצג UPPER_SNAKE_CASE.
domain

string

הקיבוץ הלוגי שאליו שייך ה'נימוק'. דומיין השגיאה הוא בדרך כלל שם השירות הרשום של הכלי או המוצר שיצרו את השגיאה. לדוגמה: "pubsub.googleapis.com". אם השגיאה נוצרת על ידי תשתית נפוצה, דומיין השגיאה צריך להיות ערך ייחודי גלובלית שמזהה את התשתית. בתשתית של Google API, דומיין השגיאה הוא googleapis.com.
metadata

map<string, string>

פרטים מובְנים נוספים על השגיאה הזו.

המפתחות צריכים להתאים לביטוי רגולרי של [a-z][a-zA-Z0-9-_]+, אבל מומלץ להשתמש בשיטת lowerCamelCase. בנוסף, האורך שלהם צריך להיות מוגבל ל-64 תווים. כשמזהים את הערך הנוכחי של חריגה ממגבלה, היחידות צריכות להיכלל במפתח ולא בערך. לדוגמה, במקום {"instanceLimit": "100/request"}, צריך להחזיר את הערך {"instanceLimitPerRequest": "100"}, אם הלקוח חורג ממספר המופעים שאפשר ליצור בבקשה אחת (בקשת אצווה).

עזרה

הוא מספק קישורים לתיעוד או לביצוע פעולה מחוץ לפס.

לדוגמה, אם בדיקת מכסת השימוש נכשלה עם שגיאה שמציינת שהפרויקט שמבצע את הקריאה לא הפעיל את השירות שאליו יש גישה, יכול להיות שהשגיאה תכלול כתובת URL שמפנה ישירות למקום הנכון במסוף המפתחים כדי להפעיל את השירות.

שדות

LocalizedMessage

הפונקציה מספקת הודעת שגיאה מותאמת לשפה המקומית שאפשר להחזיר למשתמש, ואפשר לצרף אותה לשגיאת RPC.

שדות
locale

string

הלוקאל שבו נעשה שימוש בהתאם למפרט שמוגדר בכתובת https://www.rfc-editor.org/rfc/bcp/bcp47.txt. דוגמאות: en-US,‏ fr-CH,‏ es-MX
message

string

הודעת השגיאה שהותאמה לשוק המקומי בלוקאל שלמעלה.

RequestInfo

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

שדות
request_id

string

מחרוזת אטומה שרק השירות שיצר אותה יכול לפרש. לדוגמה, אפשר להשתמש בו כדי לזהות בקשות ביומנים של השירות.
serving_data

string

כל הנתונים ששימשו להצגת הבקשה הזו. לדוגמה, דוח קריסות מוצפן שאפשר לשלוח בחזרה לספק השירות לצורך ניפוי באגים.

סטטוס

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

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

שדות
code

int32

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

string

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

Any

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