Status

סוג Status מגדיר מודל שגיאה לוגי המתאים לסביבות תכנות שונות, כולל REST APIs ו-RPC APIs. הוא נמצא בשימוש על ידי 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" } .