このページでは、バックエンド API メソッドのパスやクエリ パラメータの中で API パラメータ型として使用できるデータ型と、メソッドの戻り値の型やリクエスト本文の型として使用できるデータ型を記載しています。
パスとクエリのパラメータでサポートされる型
パスとクエリのパラメータでサポートされる型は次のとおりです。
java.lang.String
java.lang.Boolean
とboolean
java.lang.Integer
とint
java.lang.Long
とlong
java.lang.Float
とfloat
java.lang.Double
とdouble
java.util.Date
com.google.api.server.spi.types.DateAndTime
com.google.api.server.spi.types.SimpleDate
- 任意の
enum
- ここで一覧表示されている型の配列または
java.util.Collection
。他の型の配列やコレクションはサポートされていません。
パラメータをパスパラメータまたはクエリ パラメータとして指定するには、パラメータに @Named
アノテーションを付けます。例:
public Resource get(@Named("id") int id) { … }
パスパラメータ
パスパラメータは、@ApiMethod
アノテーションの path
プロパティに含まれるメソッド パラメータです。path
が指定されていない場合、アノテーション @Nullable
または @DefaultValue
が付いていないすべてのパラメータが自動的にパスパラメータとしてパスに追加されます。例:
public Resource get(@Named("id") int id) { … }
path
に手動でパラメータを追加するには、パラメータ名を {}
マークで囲んでパスに含めます。手動で path
に追加されたパラメータにアノテーション @Nullable
または @DefaultValue
を付けることはできません。例:
@ApiMethod(path = "resources/{id}")
public Resource get(@Named("id") int id) { … }
クエリ パラメータ
クエリ パラメータは、@ApiMethod
アノテーションの path
プロパティに含まれないメソッド パラメータです。オプションのパラメータ、つまり @Nullable
または @DefaultValue
アノテーションが付いたパラメータは自動的に path
に追加されないので、path
が指定されなければ自動的にクエリ パラメータになることに注意してください。例:
public Resource get(@Named("id") @Nullable int id) { … }
path
が指定されている場合、パラメータを path
に含めないことで、そのパラメータをクエリ パラメータにすることができます。例:
@ApiMethod(path = "resources")
public Resource get(@Named("id") int id) { … }
インジェクション型
インジェクション型は、Cloud Endpoints Frameworks によって特別に処理される型です。このような型がメソッド パラメータとして使用される場合は、API の一部にはなりません。代わりに、Endpoints Frameworks によってパラメータが入力されます。
インジェクション型は次のとおりです。
com.google.appengine.api.users.User
javax.servlet.http.HttpServletRequest
javax.servlet.ServletContext
エンティティ型
Endpoints Frameworks のドキュメントでは、「エンティティ型」は Java Beans と同義です。API で使用するために定義するクラスは、次の条件を満たす必要があります。
- 引数を取らないパブリック コンストラクタが含まれる。
- getter と setter を使用してプライベート プロパティへのアクセスを制御する。 また、各 setter はパラメータを 1 つだけ受け入れる。
通常、エンティティ型では Serializable も実装されますが、Endpoints Frameworks を使用する際には、これは必須ではありません。
エンティティ型のパラメータには @Named
アノテーションを使用しないでください。
リクエスト本文
エンティティ型をメソッドのパラメータとして渡すと、エンティティ型のプロパティは、リクエスト本文の JSON フィールドにマッピングされます。メソッドに含めるエンティティ型のパラメータは 1 つのみにする必要があります。次に例を示します。
public Resource set(Resource resource) { … }
エンティティ型以外の複数のパラメータと、1 つのエンティティ型のパラメータをメソッドに含めることができます。次に例を示します。
@ApiMethod(name = "echo")
public Message echo(Message message, @Named("n") @Nullable Integer n) { … }
上記の例では、message
パラメータのプロパティがリクエスト本文の JSON フィールドにマッピングされます。@Nullable
アノテーションは n
パラメータがオプションであることを示しているため、これがクエリ パラメータとして渡されます。
レスポンス オブジェクト
メソッドの戻り値は、次のいずれかにする必要があります。
- エンティティ型
- ジェネリック型
- CollectionResponse(
com.google.api.server.spi.response.CollectionResponse
)、または CollectionResponse のサブクラス
レスポンス オブジェクトの JSON フィールドは、戻り値のプロパティからマッピングされます。
@ApiTransformer
が型に与える影響
@ApiTransformer
を使用する場合は、変換が型に与える影響に注意する必要があります。
@ApiTransformer
とパラメータ型
@ApiTransformer
を使用する場合、変換後のメソッド パラメータがパラメータ型とみなされるかどうかは、元の型ではなく、変換の結果に依存します。ある型がパラメータ型に変換された場合、そのメソッド パラメータは API パラメータとみなされ、@Named
アノテーションを付ける必要があります。
@ApiTransformer
とエンティティ型
同様に、メソッド パラメータや戻り値の型がエンティティ型とみなされるかどうかは、元の型ではなく、変換の結果に依存します。ある型がエンティティ型に変換された場合、その型は戻り値の型として使用できます。メソッド パラメータとして使用される場合は、その型はエンティティ型と見なされるため、@Named
アノテーションを付けることはできません。
@ApiTransformer
とインジェクション型
インジェクション型は @ApiTransformer
の影響を受けません。変換前の元の型がインジェクション型である場合にのみ、メソッド パラメータはインジェクション型とみなされます。