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 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 jalur

Parameter jalur adalah parameter metode yang disertakan dalam properti path dari 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 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 menjadikan parameter sebagai 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 diisi oleh Framework Endpoint.

Jenis yang dimasukkan adalah sebagai berikut:

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

Jenis entitas

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

  • Memiliki konstruktor publik yang tidak memerlukan argumen.
  • Kontrol akses ke properti pribadi menggunakan pengambil dan penyetel. Selain itu, setiap penyetel hanya boleh menggunakan 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 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 dalam 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:

  • Jenis entity
  • 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 menggunakan @ApiTransformer, Anda perlu mengetahui pengaruh transformasi terhadap jenis tersebut.

@ApiTransformer dan jenis parameter

Saat @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 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 pada 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 dianotasikan 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.