例外狀況與 HTTP 狀態碼

本頁面列出 endpoints 程式庫提供的例外狀況,以及 Cloud Endpoints Frameworks 支援的 HTTP 狀態碼。

在許多情況下,您可能會想要使用常見 HTTP 狀態碼來表示使用者的 API 要求成功或失敗。舉例來說,如果使用者嘗試擷取不存在的實體,您可能會想要傳送 HTTP 404 狀態碼來表示不存在任何 ID 為 entityId 的實體。

您可以擲回 endpoints 程式庫提供的例外狀況,以傳送常見的 HTTP 狀態碼,如下所示:

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 支援在 API 回應中使用 HTTP 狀態碼子集。下表說明支援的狀態碼。

HTTP 狀態碼 支援
HTTP 2xx 如果 API 方法成功傳回,則 Endpoints Frameworks 通常會假設狀態碼為 HTTP 200
如果 API 方法回應類型為 void 或 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 所有 HTTP 5xx 狀態碼在用戶端回應中都會轉換為 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>
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁