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[1].email להפרה בשדה email של ההודעה הראשונה email_addresses
  • ‫email_addresses[3].type[2] להפרה בערך השני type במסר השלישי email_addresses.

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

  • ‫fullName על הפרה של הערך fullName
  • ‫emailAddresses[1].email להפרה בשדה email של ההודעה הראשונה emailAddresses
  • ‫emailAddresses[3].type[2] להפרה בערך השני 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 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 ביט לקרוא נתונים בהיסט שלא נמצא בטווח [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

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

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