Parameter dan jenis 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 jalur dan parameter 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 apa pun atau java.util.Collection dari jenis yang tercantum di sini. Array atau koleksi jenis lain tidak didukung.

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

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

Parameter lokasi

Parameter jalur adalah parameter metode yang disertakan dalam properti path anotasi @ApiMethod. Jika path tidak ditentukan, parameter apa pun yang tidak dianotasi 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 pada anotasi @ApiMethod. Perhatikan bahwa parameter opsional, yaitu yang diberi anotasi @Nullable atau @DefaultValue, tidak pernah otomatis ditambahkan ke path, sehingga parameter tersebut otomatis mengkueri parameter 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 dimasukkan

Jenis yang dimasukkan adalah jenis yang menerima perlakuan khusus oleh Framework Cloud Endpoints. Jika jenis tersebut digunakan sebagai parameter metode, jenis tersebut tidak menjadi bagian dari API. Sebagai gantinya, parameter tersebut diisi oleh Framework Endpoint.

Jenis yang dimasukkan adalah sebagai berikut:

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

Jenis entity

Dalam dokumentasi Framework Endpoint, jenis entity mirip dengan Java Bean. Class yang Anda tentukan untuk digunakan dalam API harus:

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

Biasanya, jenis entity juga mengimplementasikan Serializable, tetapi ini bukan persyaratan untuk menggunakan Framework Endpoint.

Jangan gunakan anotasi @Named untuk parameter jenis entity.

Isi permintaan

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

public Resource set(Resource resource) { … }

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

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

Pada contoh sebelumnya, properti di parameter message dipetakan ke kolom JSON dalam 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 ini:

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

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

Efek @ApiTransformer pada jenis

Jika menggunakan @ApiTransformer, Anda perlu mengetahui dampak transformasi terhadap jenis tersebut.

@ApiTransformer dan jenis parameter

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

@ApiTransformer dan jenis entity

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

@ApiTransformer dan jenis yang dimasukkan

Jenis yang dimasukkan tidak terpengaruh oleh @ApiTransformer. Parameter metode hanya dianggap sebagai jenis yang dimasukkan jika jenis aslinya yang tidak ditransformasi adalah jenis yang dimasukkan.