Status

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

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

סקירה כללית

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

מיפוי שפות

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

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

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

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

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

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

  • פעולות באצווה. אם לקוח משתמש בבקשה באצווה ובתגובה באצווה, יש להשתמש בהודעת 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" }.