Anotasi dan sintaksis Cloud Endpoints Frameworks

Anotasi Framework Endpoint menjelaskan konfigurasi API, metode, parameter, dan detail penting lainnya yang menentukan properti dan perilaku endpoint.

Lihat Menulis dan membuat anotasi kode untuk mengetahui informasi tentang cara menambahkan anotasi menggunakan project Maven. Artefak Cloud Endpoints App Engine Maven disediakan untuk membuat dan mem-build API backend, serta membuat library klien dari API tersebut.

Anotasi yang menentukan konfigurasi dan perilaku di seluruh API (memengaruhi semua class yang diekspos dalam API dan semua metodenya) adalah @Api. Semua metode publik, non-statis, dan non-bridge dari class yang dianotasikan dengan @Api akan ditampilkan dalam API publik.

Jika memerlukan konfigurasi API khusus untuk metode tertentu, Anda dapat memilih untuk menggunakan @ApiMethod untuk menetapkan konfigurasi per metode. Anda mengonfigurasi anotasi ini dengan menyetel berbagai atribut, seperti yang ditunjukkan dalam tabel berikut.

@Api: Anotasi cakupan API

Anotasi @Api mengonfigurasi seluruh API, dan berlaku untuk semua metode publik dari suatu class kecuali jika diganti oleh @ApiMethod.

Untuk mengganti anotasi @Api tertentu untuk class tertentu dalam API, lihat @ApiClass dan @ApiReference.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.Api;

Atribut

Contoh anotasi @Api

Anotasi ini ditempatkan sebelum definisi class:

/** An endpoint class we are exposing. */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
        ownerName = "helloworld.example.com",
        packagePath = ""))

Client-ID dan audiens

Untuk autentikasi OAuth2, token OAuth2 diterbitkan ke client ID tertentu, yang berarti Anda dapat menggunakan client ID untuk membatasi akses ke API. Saat mendaftarkan aplikasi Android di Konsol Google Cloud, Anda membuat client ID untuk aplikasi tersebut. Client ID ini adalah ID yang meminta token OAuth2 dari Google untuk tujuan autentikasi. Jika API backend dilindungi oleh autentikasi, token akses OAuth2 akan dikirim dan dibuka oleh Endpoint, client ID diekstrak dari token, lalu ID tersebut dibandingkan dengan daftar client ID yang dapat diterima yang dideklarasikan backend (daftar clientIds).

Jika ingin Endpoints API mengautentikasi pemanggil, Anda harus menyediakan daftar clientIds yang diizinkan untuk meminta token. Daftar ini harus berisi semua client ID yang Anda peroleh melalui Google Cloud Console untuk klien web atau Android Anda. Artinya, klien harus diketahui pada waktu build API. Jika Anda menetapkan daftar kosong, {}, tidak ada klien yang dapat mengakses metode yang dilindungi oleh Auth.

Jika Anda menggunakan atribut clientIds dan ingin menguji panggilan yang diautentikasi ke API menggunakan Google API Explorer, Anda harus menyediakan client ID-nya dalam daftar clientIds: nilai yang akan digunakan adalah com.google.api.server.spi.Constant.API_EXPLORER_CLIENT_ID.

Tentang audiens

Daftar clientIds melindungi API backend dari klien yang tidak sah. Namun, perlindungan lebih lanjut diperlukan untuk melindungi klien, sehingga token autentikasinya hanya berfungsi untuk API backend yang dimaksud. Untuk klien Android, mekanisme ini adalah atribut audiences, tempat Anda menetapkan client ID API backend.

Perlu diperhatikan bahwa saat Anda membuat project konsol Google Cloud, client ID default akan otomatis dibuat dan diberi nama untuk digunakan oleh project tersebut. Saat Anda mengupload backend API ke App Engine, API tersebut akan menggunakan client ID tersebut. Ini adalah client ID web yang disebutkan dalam autentikasi API.

@ApiMethod: Anotasi cakupan metode

Anotasi @ApiMethod digunakan untuk menyediakan konfigurasi API yang berbeda dengan default yang disediakan oleh anotasi @Api atau @ApiClass. Perhatikan bahwa ini bersifat opsional: semua metode publik, non-statis, dan non-bridge di class dengan anotasi @Api akan ditampilkan di API, baik metode tersebut memiliki anotasi @ApiMethod atau tidak.

Atribut dalam anotasi ini memungkinkan Anda mengonfigurasi detail satu metode API. Jika atribut yang sama ditentukan dalam @Api dan @ApiMethod, @ApiMethod akan diganti.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.AnnotationBoolean;
import com.google.api.server.spi.config.ApiMethod;
import com.google.api.server.spi.config.ApiMethod.HttpMethod;

Atribut

Contoh anotasi @ApiMethod

Anotasi ini ditempatkan sebelum definisi metode di dalam class:

/** A simple endpoint method that takes a name and says Hi back. */
@ApiMethod(
    name = "sayHiUser",
    httpMethod = ApiMethod.HttpMethod.GET)
public MyBean sayHiUser(@Named("name") String name, User user)
    throws OAuthRequestException, IOException {
  MyBean response = new MyBean();
  response.setData("Hi, " + name + "(" + user.getEmail() + ")");

  return response;
}

Metode yang menggunakan entity sebagai parameter harus menggunakan HttpMethod.POST (untuk operasi penyisipan) atau HttpMethod.PUT (untuk operasi update):

@ApiMethod(
    name = "mybean.insert",
    path = "mybean",
    httpMethod = ApiMethod.HttpMethod.POST
)
public void insertFoo(MyBean foo) {
}

@Named

Anotasi @Named diperlukan untuk semua parameter jenis non-entity yang diteruskan ke metode sisi server. Anotasi ini menunjukkan nama parameter dalam permintaan yang dimasukkan di sini. Parameter yang tidak dianotasi dengan @Named dimasukkan dengan seluruh objek permintaan.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import javax.inject.Named;

Contoh ini menunjukkan penggunaan @Named:

/** A simple endpoint method that takes a name and says Hi back. */
@ApiMethod(name = "sayHi")
public MyBean sayHi(@Named("name") String name) {
  MyBean response = new MyBean();
  response.setData("Hi, " + name);

  return response;
}

dengan @Named menentukan bahwa hanya parameter id yang dimasukkan dalam permintaan.

@ApiLimitMetric

Bagian ini menjelaskan anotasi yang diperlukan untuk menentukan quotas untuk API Anda. Baca artikel Mengonfigurasi kuota untuk mengetahui semua langkah yang diperlukan dalam menyiapkan kuota.

Anda menetapkan anotasi @ApiLimitMetric ke atribut limitDefinitions dari anotasi cakupan API. Anda juga harus menambahkan @ApiMetricCost ke anotasi @ApiMethod untuk setiap metode yang ingin Anda terapkan kuotanya.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.ApiLimitMetric;

Atribut

Contoh

limitDefinitions = {
      @ApiLimitMetric(
        name = "read-requests",
        displayName = "Read requests",
        limit = 1000),
      @ApiLimitMetric(
        name = "write-requests",
        displayName = "Write requests",
        limit = 50),
    }

@ApiNamespace

Anotasi @ApiNamespace menyebabkan library klien yang dihasilkan memiliki namespace yang Anda tentukan, bukan default yang dibuat selama pembuatan library klien.

Secara default, jika Anda tidak menggunakan anotasi ini, namespace yang digunakan adalah kebalikan dari your-project-id.appspot.com. Artinya, jalur paketnya adalah com.appspot.your-project-id.yourApi.

Anda dapat mengubah namespace default dengan menyediakan anotasi @ApiNamespace dalam anotasi @Api:

/** An endpoint class we are exposing. */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
        ownerName = "helloworld.example.com",
        packagePath = ""))

Tetapkan atribut ownerDomain ke domain perusahaan Anda sendiri dan ownerName ke nama perusahaan Anda, misalnya, your-company.com. Kebalikan dari ownerDomain digunakan untuk jalur paket: com.your-company.yourApi.

Anda dapat memilih menggunakan atribut packagePath untuk memberikan cakupan lebih lanjut. Misalnya, dengan menetapkan packagePath ke cloud, jalur paket yang digunakan di library klien adalah com.your-company.cloud.yourApi. Anda dapat menambahkan lebih banyak nilai ke jalur paket dengan memberikan pemisah /: packagePath="cloud/platform".

@Nullable

Anotasi ini menunjukkan bahwa parameter metode bersifat opsional (dan oleh karena itu, parameter kueri). @Nullable hanya dapat digunakan dengan parameter @Named.

@ApiClass

Dalam multiclass API, Anda dapat menggunakan @ApiClass untuk menentukan properti yang berbeda untuk class tertentu, yang akan menggantikan properti setara dalam konfigurasi @Api. Lihat Menggunakan @ApiClass untuk properti yang dapat berbeda di antara class untuk mengetahui deskripsi lengkap anotasi ini.

@ApiReference

Dalam multiclass API, Anda dapat menggunakan @ApiReference untuk menyediakan metode alternatif pewarisan anotasi. Lihat Menggunakan pewarisan @ApiReference untuk deskripsi lengkap anotasi ini.

@ApiResourceProperty

@ApiResourceProperty memberikan kontrol atas cara properti resource ditampilkan di API. Anda dapat menggunakannya pada pengambil atau penyetel properti untuk menghapus properti dari resource API. Anda juga dapat menggunakannya di kolom itu sendiri, jika kolom bersifat pribadi, untuk mengeksposnya dalam API. Anda juga dapat menggunakan anotasi ini untuk mengubah nama properti di resource API.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.ApiResourceProperty;
import com.google.api.server.spi.config.AnnotationBoolean;

Atribut

Class contoh dengan @ApiResourceProperty

Cuplikan berikut menunjukkan class dengan pengambil properti yang dianotasi dengan @ApiResourceProperty:

class Resp {
  private String foobar = "foobar";
  private String bin = "bin";

  @ApiResourceProperty
  private String visible = "nothidden";

  @ApiResourceProperty(ignored = AnnotationBoolean.TRUE)
  public String getBin() {
    return bin;
  }

  public void setBin(String bin) {
    this.bin = bin;
  }

  @ApiResourceProperty(name = "baz")
  public String getFoobar() {
    return foobar;
  }

  public void setFoobar(String foobar) {
    this.foobar = foobar;
  }
}

public Resp getResp() {
  return new Resp();
}

Dalam cuplikan kode sebelumnya, @ApiResourceProperty diterapkan ke pengambil getBin untuk properti bin, dengan setelan atribut ignored yang memberi tahu Endpoints Frameworks untuk menghapus properti ini di resource API.

@ApiResourceProperty juga diterapkan ke kolom pribadi visible, yang tidak memiliki pengambil atau penyetel. Penggunaan anotasi ini akan mengekspos kolom ini sebagai properti dalam resource API.

Dalam cuplikan yang sama, @ApiResourceProperty juga diterapkan ke pengambil yang berbeda, getFoobar, yang menampilkan nilai properti untuk properti foobar. Atribut name dalam anotasi ini memberi tahu Framework Endpoint untuk mengubah nama properti di resource API. Nilai properti itu sendiri tidak berubah.

Dalam contoh cuplikan sebelumnya, representasi JSON dari objek Resp terlihat mirip dengan yang berikut ini:

{"baz": "foobar", "visible": "nothidden"}

@ApiTransformer

Anotasi @ApiTransformer menyesuaikan cara suatu jenis diekspos di Endpoint melalui transformasi ke dan dari jenis lain. (Transformer yang ditentukan harus merupakan implementasi dari com.google.api.server.spi.config.Transformer.)

Menggunakan anotasi @ApiTransformer pada class adalah cara yang lebih disukai untuk menentukan Transformer. Namun, Anda dapat menentukan transformer kustom dalam atribut transformer anotasi @Api.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.ApiTransformer;

Class contoh dengan @ApiTransformer

Cuplikan berikut menunjukkan class yang dianotasi dengan @ApiTransformer:

@ApiTransformer(BarTransformer.class)
public class Bar {
  private final int x;
  private final int y;

  public Bar(int x, int y) {
    this.x = x;
    this.y = y;
  }

  public int getX() {
    return x;
  }

  public int getY() {
    return y;
  }
}

Class ini ditransformasikan oleh class BarTransformer.

Contoh class transformer Endpoints

Cuplikan berikut menunjukkan contoh class transformer yang bernama BarTransformer. Ini adalah transformer yang dirujuk oleh @ApiTransformer dalam cuplikan sebelumnya:

public class BarTransformer implements Transformer<Bar, String> {
  public String transformTo(Bar in) {
    return in.getX() + "," + in.getY();
  }

  public Bar transformFrom(String in) {
    String[] xy = in.split(",");
    return new Bar(Integer.parseInt(xy[0]), Integer.parseInt(xy[1]));
  }
}

Dengan asumsi ada objek dengan properti bar dari jenis Bar, tanpa transformator sebelumnya, objek tersebut direpresentasikan sebagai:

{"bar": {"x": 1, "y": 2}}

Dengan transformer, objek akan direpresentasikan sebagai:

{"bar": "1,2"}