サポートされるパラメータと戻り値の型

このページでは、バックエンド 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 の影響を受けません。変換前の元の型がインジェクション型である場合にのみ、メソッド パラメータはインジェクション型とみなされます。