סוג 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 | קוד הסטטוס, שאמור להיות ערך enum של |
message | הודעת שגיאה הפונה למפתח, שאמורה להיות באנגלית. כל הודעת שגיאה הפונה למשתמש צריכה להיות מקומית ולשלוח בשדה |
details[] | רשימה של הודעות הנושאות את פרטי השגיאה. יש קבוצה נפוצה של סוגי הודעות לשימוש ממשקי API. אובייקט המכיל שדות מסוג שרירותי. שדה נוסף |