Status

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

  • קל לשימוש ולהבנה עבור רוב המשתמשים
  • גמיש מספיק כדי לענות על צרכים בלתי צפויים

סקירה כללית

ההודעה Status מכילה שלושה סוגי נתונים: קוד שגיאה, הודעת שגיאה ופרטי שגיאה. קוד השגיאה צריך להיות ערך enum של google.rpc.Code, אבל יכול להיות שהוא יקבל קודי שגיאה נוספים אם יהיה צורך. הודעת השגיאה צריכה להיות הודעה באנגלית שמיועדת למפתחים, ועוזרת להם להבין את השגיאה ולפתור אותה. אם צריך להציג למשתמש הודעת שגיאה בשפה מקומית, צריך להוסיף את ההודעה המתורגמת לפרטי השגיאה או לתרגם אותה בלקוח. פרטי השגיאה האופציונליים עשויים להכיל מידע שרירותי על השגיאה. יש קבוצה מוגדרת מראש של סוגי פרטי שגיאה בחבילה google.rpc שאפשר להשתמש בהם לתנאי שגיאה נפוצים.

מיפוי שפות

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

שימושים אחרים

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

דוגמאות לשימוש במודל השגיאות הזה:

  • שגיאות חלקיות. אם שירות צריך להחזיר שגיאות חלקיות ללקוח, הוא יכול להטמיע את Status בתגובה הרגילה כדי לציין את השגיאות החלקיות.

  • שגיאות בתהליך העבודה. תהליך עבודה טיפוסי כולל כמה שלבים. בכל שלב יכולה להופיע Status הודעה לדיווח על שגיאות.

  • פעולות באצווה. אם לקוח משתמש ב-Batch request ובתגובת אצווה, צריך להשתמש בהודעה Status ישירות בתוך תגובת האצווה, אחת לכל תגובת משנה של שגיאה.

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

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

ייצוג ב-JSON 
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
שדות
code

number

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

message

string

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

details[]

object

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

אובייקט שמכיל שדות מכל סוג שהוא. שדה נוסף "@type" מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.