חריגים וקודי סטטוס של HTTP

בדף הזה מפורטים החריגים שסופקו על ידי ספריית endpoints וקודי המצב של HTTP שנתמכים על ידי Cloud Endpoints Frameworks.

במקרים רבים, כדאי להשתמש בקודי סטטוס נפוצים של HTTP כדי לציין אם בקשת API של משתמש הצליחה או נכשלה. לדוגמה, אם משתמש מנסה לאחזר ישות שלא קיימת, יכול להיות שתרצו לשלוח קוד סטטוס HTTP 404 כדי לציין שלא קיימת ישות עם המזהה: entityId.

אפשר לשלוח קודי סטטוס נפוצים של HTTP על ידי הפעלת חריגה שסופקה על ידי ספריית endpoints באופן הבא:

throw new NotFoundException(user.getEmail());

חריגים שסופקו על ידי Endpoints Frameworks

‫Endpoints Frameworks מספק את החריגים הבאים, שמתאימים לקודי סטטוס ספציפיים של HTTP:

חריג קוד סטטוס של HTTP מתאים
com.google.api.server.spi.response.BadRequestException HTTP 400
com.google.api.server.spi.response.UnauthorizedException HTTP 401
com.google.api.server.spi.response.ForbiddenException HTTP 403
com.google.api.server.spi.response.NotFoundException HTTP 404
com.google.api.server.spi.response.ConflictException HTTP 409
com.google.api.server.spi.response.InternalServerErrorException HTTP 500
com.google.api.server.spi.response.ServiceUnavailableException HTTP 503

קודי סטטוס נתמכים של HTTP

‫Cloud Endpoints Frameworks תומך בקבוצת משנה של קודי סטטוס HTTP בתשובות של API. בטבלה הבאה מתוארים הקודים הנתמכים.

קודי סטטוס של HTTP תמיכה
HTTP 2xx בדרך כלל, אם ה-method של ה-API מחזיר ערך בהצלחה, ה-Frameworks של Endpoints מניח שקוד הסטטוס של ה-HTTP הוא 200.
אם סוג התגובה של ה-method של ה-API הוא void או שערך ההחזרה של ה-method של ה-API הוא null, קוד הסטטוס של ה-HTTP מוגדר ל-204.
HTTP 3xx אין תמיכה בקודים מסוג HTTP 3xx. שימוש בכל קודי HTTP 3xx מוביל לתגובת HTTP 404.
HTTP 4xx רק קודי ה-HTTP 4xx הבאים נתמכים:
  • 400
  • 401
  • 403
  • 404
  • 409
  • 410
  • 412
  • 413
כל קודי ה-HTTP 4xx האחרים מוחזרים כשגיאה 404, למעט הקודים הבאים:
  • הערך 405 מוחזר כ-501
  • הערך 408 מוחזר כ-503
HTTP 5xx כל קודי הסטטוס 5xx של HTTP מומרים ל-HTTP 503 בתגובת הלקוח.

יצירת מחלקות חריגות משלכם

אם רוצים ליצור מחלקות חריגות אחרות לקודי סטטוס אחרים של HTTP, צריך ליצור מחלקת משנה של com.google.api.server.spi.ServiceException. בקטע הקוד הבא אפשר לראות איך יוצרים מחלקת חריגים שמייצגת קוד סטטוס HTTP 408:

import com.google.api.server.spi.ServiceException;

// Exceptions must inherit from ServiceException
public class RequestTimeoutException extends ServiceException {
  public RequestTimeoutException(String message) {
    super(408, message);
  }
}

שימוש בקודים לא נתמכים של סטטוס HTTP

אפשר להשתמש בקודים של מצב HTTP שלא מופיעים ברשימה הקודמת של הקודים הנתמכים. שימו לב שאם תעשו את זה, יכול להיות שיהיו לכך השלכות לא מכוונות על ספריות לקוח שניגשות ל-API. כדי להשתמש בקודי שגיאה שלא נתמכים, צריך ליצור מחלקת חריגים משלכם, כמו שמתואר בקטע הקודם, ולהוסיף פרמטר חדש לאתחול של servlet‏ enableExceptionCompatibility אל EndpointsServlet:

  <servlet>
    <servlet-name>com.google.api.server.spi.EndpointsServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
    <init-param>
      <param-name>services</param-name>
      <param-value>...</param-value>
    </init-param>
    <init-param>
      <param-name>enableExceptionCompatibility</param-name>
      <param-value>true</param-value>
    </init-param>
  </servlet>