Jenis parameter dan nilai yang ditampilkan yang didukung

Halaman ini mencantumkan jenis data yang dapat Anda gunakan sebagai jenis parameter API di parameter jalur atau kueri untuk metode API backend, dan jenis yang dapat Anda gunakan sebagai jenis nilai yang ditampilkan metode atau jenis isi permintaan.

Jenis yang didukung untuk parameter jalur dan kueri

Jenis yang didukung untuk parameter jalur dan kueri adalah sebagai berikut:

  • java.lang.String
  • java.lang.Boolean dan boolean
  • java.lang.Integer dan int
  • java.lang.Long dan long
  • java.lang.Float dan float
  • java.lang.Double dan double
  • java.util.Date
  • com.google.api.server.spi.types.DateAndTime
  • com.google.api.server.spi.types.SimpleDate
  • enum apa pun
  • Array atau java.util.Collection dari jenis yang tercantum di sini. Array atau kumpulan jenis lainnya tidak didukung.

Untuk menentukan parameter sebagai parameter jalur atau kueri, beri anotasi parameter dengan @Named. Contoh:

public Resource get(@Named("id") int id) { … }

Parameter jalur

Parameter jalur adalah parameter metode yang disertakan dalam properti path dari anotasi @ApiMethod. Jika path tidak ditentukan, semua parameter yang tidak diberi anotasi dengan @Nullable atau @DefaultValue akan otomatis ditambahkan ke jalur sebagai parameter jalur. Contoh:

public Resource get(@Named("id") int id) { … }

Untuk menambahkan parameter ke path secara manual, sertakan nama parameter dalam tanda {} di jalur. Parameter yang ditambahkan secara manual ke path tidak dapat dianotasi dengan @Nullable atau @DefaultValue. Contoh:

@ApiMethod(path = "resources/{id}")
public Resource get(@Named("id") int id) { … }

Parameter kueri

Parameter kueri adalah parameter metode yang tidak disertakan dalam properti path dari anotasi @ApiMethod. Perhatikan bahwa parameter opsional, yaitu parameter yang dianotasi dengan @Nullable atau @DefaultValue, tidak pernah otomatis ditambahkan ke path, sehingga parameter tersebut otomatis menjadi parameter kueri jika tidak ada path yang ditentukan. Contoh:

public Resource get(@Named("id") @Nullable int id) { … }

Jika path ditentukan, Anda dapat membuat parameter menjadi parameter kueri dengan tidak menyertakannya dalam path. Contoh:

@ApiMethod(path = "resources")
public Resource get(@Named("id") int id) { … }

Jenis yang diinjeksikan

Jenis yang disuntikkan adalah jenis yang menerima perlakuan khusus oleh Cloud Endpoints Frameworks. Jika jenis tersebut digunakan sebagai parameter metode, jenis tersebut tidak dijadikan bagian dari API. Sebagai gantinya, parameter diisi oleh Endpoints Frameworks.

Jenis yang disuntikkan adalah sebagai berikut:

  • com.google.appengine.api.users.User
  • javax.servlet.http.HttpServletRequest
  • javax.servlet.ServletContext

Jenis entitas

Dalam dokumentasi Endpoints Frameworks, jenis entitas sama dengan Java Beans. Class yang Anda tentukan untuk digunakan di API Anda harus:

  • Memiliki konstruktor publik yang tidak memerlukan argumen.
  • Mengontrol akses ke properti pribadi menggunakan pengambil dan penyetel. Selain itu, setiap setter hanya boleh mengambil satu parameter.

Biasanya jenis entity juga menerapkan Serializable, tetapi ini bukan persyaratan untuk menggunakan Endpoints Frameworks.

Jangan gunakan anotasi @Named untuk parameter jenis entity.

Isi permintaan

Saat Anda meneruskan jenis entity sebagai parameter dalam metode, properti dalam jenis entity dipetakan ke kolom JSON di isi permintaan. Metode Anda hanya boleh berisi satu parameter jenis entitas. Contoh:

public Resource set(Resource resource) { … }

Anda dapat menyertakan parameter jenis non-entitas dan parameter jenis entitas dalam metode. Contoh:

@ApiMethod(name = "echo")
public Message echo(Message message, @Named("n") @Nullable Integer n) { … }

Pada contoh sebelumnya, properti dalam parameter message dipetakan ke kolom JSON di isi permintaan. Anotasi @Nullable menunjukkan bahwa parameter n bersifat opsional, sehingga diteruskan sebagai parameter kueri.

Objek respons

Nilai yang ditampilkan metode harus berupa salah satu dari berikut:

  • Jenis entitas
  • Jenis generik
  • CollectionResponse (com.google.api.server.spi.response.CollectionResponse) atau subclass CollectionResponse

Kolom JSON dalam objek respons dipetakan dari properti dalam nilai yang ditampilkan.

Pengaruh @ApiTransformer pada jenis

Jika Anda menggunakan @ApiTransformer, Anda harus mengetahui pengaruh transformasi terhadap jenis.

@ApiTransformer dan jenis parameter

Jika @ApiTransformer digunakan, apakah parameter metode yang dihasilkan dianggap sebagai jenis parameter atau tidak bergantung pada hasil transformasi, bukan pada jenis aslinya. Jika jenis diubah menjadi jenis parameter, parameter metode dianggap sebagai parameter API dan harus diberi anotasi dengan @Named.

@ApiTransformer dan jenis entity

Demikian pula, apakah parameter metode atau jenis yang ditampilkan dianggap sebagai jenis entity bergantung pada hasil transformasi, bukan pada jenis aslinya. Jika jenis diubah menjadi jenis entitas, jenis tersebut dapat digunakan sebagai jenis nilai yang ditampilkan, dan saat digunakan sebagai parameter metode, jenis tersebut tidak dapat dianotasi dengan @Named karena dianggap sebagai jenis entitas.

@ApiTransformer dan jenis yang diinjeksikan

Jenis yang disisipkan tidak terpengaruh oleh @ApiTransformer. Parameter metode hanya dianggap sebagai jenis yang disuntikkan jika jenis aslinya yang tidak diubah adalah jenis yang disuntikkan.