ここでは、endpoints
ライブラリにより提供される例外と、Cloud Endpoints Frameworks でサポートされている HTTP ステータス コードのリストを示します。
多くの場合、一般的な HTTP ステータス コードを使用して、ユーザーの API リクエストの成功または失敗を示すことをおすすめします。たとえば、ユーザーが存在しないエンティティを取得しようとしている場合は、ID が entityId
であるエンティティが存在しないことを示す HTTP 404
ステータス コードを送信します。
次のように、endpoints
ライブラリが提供する例外を指定することで、一般的な HTTP ステータス コードを送信できます。
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 コードのみがサポートされます。
404 が返されます。
|
HTTP 5xx | HTTP 5xx ステータス コードはすべて、クライアント レスポンスにおいて HTTP 503 に変換されます。 |
独自の例外クラスの作成
その他の HTTP ステータス コードに対応する他の例外クラスを作成するには、com.google.api.server.spi.ServiceException
をサブクラス化する必要があります。次のスニペットは、HTTP 408
ステータス コードを表す例外クラスの作成方法を示しています。
サポートされていない HTTP ステータス コードを使用する
前述のサポートされている HTTP ステータス コードのリストにないコードを使用することは可能です。そのようなコードを使用する場合、API にアクセスするクライアント ライブラリで予期しない結果が生じる可能性があるので、ご注意ください。サポートされていないエラーコードを使用するには、前のセクションで説明した独自の例外クラスを作成し、次のように新しいサーブレット初期化パラメータ 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>