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

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

PreconditionFailure

מתאר את התנאים המוקדמים שנכשלו.

לדוגמה, אם בקשת RPC נכשלה כי נדרש אישור של התנאים וההגבלות, יכול להיות שההפרה של התנאים וההגבלות תופיע בהודעה PreconditionFailure.

שדות
violations[]

Violation

מתאר את כל ההפרות של התנאים המוקדמים.

הפרה

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

שדות
type

string

סוג השגיאה PreconditionFailure. מומלץ להשתמש בסוג enum ספציפי לשירות כדי להגדיר את הנושאים הנתמכים של הפרת תנאים מוקדמים. לדוגמה, "TOS" עבור "הפרת התנאים וההגבלות".
subject

string

הנושא, ביחס לסוג, שנכשל. לדוגמה, הכתובת google.com/cloud ביחס לסוג 'תנאים והגבלות' תציין לאילו תנאים והגבלות מתייחסים.
description

string

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

לדוגמה: "לא אישרת את התנאים וההגבלות".

QuotaFailure

תיאור של כשל בבדיקת מכסת השימוש.

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

אפשר גם לעיין במידע על סוגי RetryInfo ו-Help כדי לקבל פרטים נוספים על טיפול בכשל במכסה.

שדות
violations[]

Violation

מתאר את כל ההפרות של המכסה.

הפרה

סוג הודעה שמשמשת לתיאור של חריגה אחת ממכסת השימוש. לדוגמה, חריגה ממכסה יומית או ממכסה מותאמת אישית.

שדות
subject

string

הנושא שעליו נכשלה בדיקת המכסה. לדוגמה, clientip:או project:.
description

string

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

לדוגמה: 'השירות מושבת' או 'הייתה חריגה מהמגבלה היומית של פעולות כבר קראתי'.
api_service

string

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

לדוגמה, אם ה-API שנקרא הוא Kubernetes Engine API ‏ (container.googleapis.com), ומתרחשת חריגה ממכסת המכסות ב-Kubernetes Engine API עצמו, הערך של השדה הזה יהיה container.googleapis.com. לעומת זאת, אם חריגה מהמכסה מתרחשת כש-Kubernetes Engine API יוצר מכונות וירטואליות ב-Compute Engine API ‏ (compute.googleapis.com), הערך בשדה הזה יהיה compute.googleapis.com.
quota_metric

string

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

לדוגמה, compute.googleapis.com/cpus_per_vm_family או storage.googleapis.com/internet_egress_bandwidth.
quota_id

string

המזהה של המכסה שהופרה. המזהה הייחודי של מכסה בהקשר של שירות API. נקרא גם 'שם המגבלה'.

לדוגמה, 'CPUS-PER-VM-FAMILY-per-project-region'.
quota_dimensions

map<string, string>

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

לדוגמה, המכסה 'מעבדים לכל אזור לכל משפחת מכונות וירטואליות' אוכפת מגבלה על המדד 'compute.googleapis.com/cpus_per_vm_family' במאפיינים 'אזור' ו'משפחת מכונות וירטואליות'. אם ההפרה התרחשה באזור us-central1 ובמשפחת מכונות וירטואליות n1, הערך של quota_dimensions יהיה:

{ "region": "us-central1", "vm_family": "n1", }

כשמכסת השימוש נאכפת באופן גלובלי, המאפיין quota_dimensions תמיד יהיה ריק.
quota_value

int64

ערך המכסה שנאכף בזמן QuotaFailure.

לדוגמה, אם ערך המכסה שנאכף בזמן QuotaFailure על מספר המעבדים הוא 10, הערך בשדה הזה ישקף את הכמות הזו.
future_quota_value

int64

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

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

RequestInfo

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

שדות
request_id

string

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

string

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

ResourceInfo

תיאור של המשאב שאליו מתבצעת גישה.

שדות
resource_type

string

שם של סוג המשאב שאליו מתבצעת הגישה, למשל 'טבלת SQL', 'מאגר Cloud Storage', 'קובץ', 'יומן Google', או כתובת ה-URL של סוג המשאב, למשל 'type.googleapis.com/google.pubsub.v1.Topic'.
resource_name

string

השם של המשאב שאליו מתבצעת גישה. לדוגמה, שם של יומן משותף: "example.com_4fghdhgsrgh@group.calendar.google.com", אם השגיאה הנוכחית היא google.rpc.Code.PERMISSION_DENIED.
owner

string

הבעלים של המשאב (אופציונלי). לדוגמה, user:או project:.
description

string

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

RetryInfo

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

תמיד מומלץ ללקוחות להשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כשמנסים שוב.

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

שדות
retry_delay

Duration

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

סטטוס

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

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

שדות
code

int32

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

string

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

Any

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