Package google.rpc

אינדקס

סטטוס

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

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

סקירה כללית

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

מיפוי שפות

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

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

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

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

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

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

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

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

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

שדות
code

int32

קוד הסטטוס, שצריך להיות ערך 'טיפוסים בני מנייה (enum)' google.rpc.Code.

message

string

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

details[]

Any

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