例外狀況與 HTTP 狀態碼

在許多情況下，您可能會想使用常見的 HTTP 狀態碼，指出使用者的 API 要求是否成功。舉例來說，如果使用者嘗試擷取不存在的實體，您可能會傳送 HTTP 404 狀態碼，表示沒有 ID 為 entity_id 的實體。

您可以提出由端點程式庫提供的例外狀況，以發送這類常見的 HTTP 狀態碼，如下所示：

message = 'No entity with the id "%s" exists.' % entity_id
raise endpoints.NotFoundException(message)

Endpoints Frameworks 提供的例外狀況

端點程式庫提供以下對應到特定 HTTP 狀態碼的例外狀況：

例外狀況 對應的 HTTP 狀態碼
endpoints.BadRequestException HTTP 400
endpoints.UnauthorizedException HTTP 401
endpoints.ForbiddenException HTTP 403
endpoints.NotFoundException HTTP 404
endpoints.InternalServerErrorException HTTP 500

支援的 HTTP 狀態碼

Cloud Endpoints Frameworks 支援在 API 回應中使用 HTTP 狀態碼子集。下表說明支援的狀態碼。

HTTP 狀態碼 支援
HTTP 2xx 如果 API 方法成功傳回，則 Endpoints Frameworks 通常會假設狀態碼為 HTTP 200。
如果 API 方法回應類型為 VoidMessage 或 API 方法的傳回值為 None，則會改為設定 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 狀態碼建立其他例外狀況類別，請將 endpoints.ServiceException 設為子類別。以下程式碼片段說明如何建立代表 HTTP 409 狀態碼的例外狀況類別：

import endpoints
import httplib

class ConflictException(endpoints.ServiceException):
  """Conflict exception that is mapped to a 409 response."""
  http_status = httplib.CONFLICT