Cloud Endpoints Frameworks 註解和語法

Endpoints Frameworks 註解說明 API 設定、方法、參數，以及其他定義端點屬性與行為的重要詳細資料。

如要瞭解如何使用 Maven 專案來加上註解，請參閱「編寫程式碼並加上註解」。我們提供 Maven App Engine Cloud Endpoints 成品，讓您能夠建構後端 API，並藉由後端 API 產生用戶端程式庫。

@Api 註解可以指定整個 API 的設定與行為 (影響 API 內所有公開類別及其公開方法)。「在類別中加上 @Api 註解的所有公開、非靜態、非橋接方法，都會在公開 API 中公開。」

如果您需為特定方法搭配特殊的 API 設定，則可以視需要使用 @ApiMethod 為個別方法進行設定。您可以透過各種屬性設定這些註解，如下方表格所示。

@Api: API-scoped annotations

除非使用 @ApiMethod 加以覆寫，否則 @Api 註解會設定整個 API，並且會套用到類別的所有公開方法。

如要覆寫 API 中特定類別的某個 @Api 註解，請參閱 @ApiClass 和 @ApiReference。

必要匯入項目

如要使用這項功能，您必須匯入以下內容：

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

屬性

範例 @Api 註解

這個註解置於類別定義之前：

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

用戶端 ID 和目標對象

針對 OAuth2 驗證，特定用戶端 ID 會獲派 OAuth2 憑證，即代表您可以使用用戶端 ID 限制他人存取您的 API。當您在 Google Cloud 控制台中註冊 Android 應用程式時，就等同為該應用程式建立用戶端 ID。這個用戶端 ID 會從 Google 要求提供 OAuth2 憑證以進行驗證。當後端 API 受驗證保護時，Endpoints 會傳送並開啟 OAuth2 存取憑證，系統會從憑證中擷取用戶端 ID，然後比較 ID 與後端宣告的可接受用戶端 ID 清單 (clientIds 清單)。

如果您想讓 Endpoints API 驗證呼叫者，您必須提供一份允許要求憑證的 clientIds 清單。這份清單應包含您透過Google Cloud console 為網路或 Android 用戶端取得的所有用戶端 ID。這代表在建構 API 時，即必須提供這些用戶端。如果您指定空白清單 {}，那表示沒有用戶端能存取驗證所保護的方法。

如果您使用 clientIds 屬性，且有意使用 Google API Explorer 對您的 API 進行驗證呼叫測試，則須在 clientIds 清單中提供其用戶端 ID：使用的值為com.google.api.server.spi.Constant.API_EXPLORER_CLIENT_ID。

關於目標對象

clientIds 清單可以「保護後端 API」，避免未經授權的用戶端存取。但是「保護用戶端」則需要進一步的防護，才能讓用戶端驗證憑證僅適用於目標後端 API。對 Android 用戶端來說，這個機制就是 audiences 屬性，您可以在其中指定後端 API 的用戶端 ID。

請注意，當您建立 Google Cloud 主控台專案時，系統會自動建立和命名提供給專案使用的預設用戶端 ID。將後端 API 上傳到 App Engine 時，會使用這個用戶端 ID，這就是 API 驗證說明中提及的網路用戶端 ID。

@ApiMethod: Method-scoped annotations

@ApiMethod 註解提供的 API 設定不同於 @Api 或 @ApiClass 註解提供的預設 API 設定。請注意，這是選用屬性。在類別中加上 @Api 註解的所有公開、非靜態、非橋接方法，不論是否有 @ApiMethod 註解，都會在 API 中公開。

本註解中的屬性允許您設定單一 API 方法的詳細資訊。如果您在 @Api 和 @ApiMethod 中指定相同的屬性，系統會以 @ApiMethod 內容覆寫。

必要匯入項目

如要使用這項功能，您需要匯入以下內容：

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;

屬性

範例 @ApiMethod 註解

這個註解是放在類別裡的方法定義前面：

/** 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;
}

將實體當成參數的方法，應使用 HttpMethod.POST (用於插入作業) 或 HttpMethod.PUT (用於更新作業)：

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

@Named

傳送至伺服器端方法的所有非實體類型參數都須使用 @Named 註解。這個註解表示在此處注入要求中的參數名稱。未加上 @Named 註解的參數會注入整個要求物件。

必要匯入項目

如要使用這項功能，您需要匯入以下內容：

import javax.inject.Named;

這個範例示範 @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;
}

其中 @Named 指定在要求中只注入 id 參數。

@ApiLimitMetric

本節說明為 API 定義配額所需使用的註解。如需瞭解設定配額必要的完整步驟，請參閱「設定配額」一文。

如果您將 @ApiLimitMetric 註解指派至 適用 API 範圍註解的 limitDefinitions 屬性，也必須針對要套用配額的每個方法，將 @ApiMetricCost 新增到 @ApiMethod 註解。

必要匯入項目

如要使用這項功能，您必須匯入以下內容：

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

屬性

範例

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

@ApiNamespace

@ApiNamespace 註解可使產生的用戶端程式庫擁有您指定的命名空間，而非產生用戶端程式庫期間所建構的預設值。

按照預設，如果不使用這項註解，則系統會使用與 your-project-id.appspot.com 反向的命名空間。也就是說，套件路徑會是 com.appspot.your-project-id.yourApi。

您可以透過在 @Api 註解中提供 @ApiNamespace 註解，來變更預設命名空間：

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

將 ownerDomain 屬性設為您自己公司的網域，並將 ownerName 設為您的公司名稱，例如 your-company.com。套件路徑會使用反向的 ownerDomain：com.your-company.yourApi。

您可以選擇使用 packagePath 屬性進一步提供範圍。例如，將 packagePath 設為 cloud，用戶端程式庫中使用的套件路徑就會是 com.your-company.cloud.yourApi。您也可以在套件路徑內加入更多的值，方法是加上分隔符號 /：packagePath="cloud/platform"。

@Nullable

本註解表示方法參數為選用 (因此為查詢參數)。@Nullable 只能與 @Named 參數一起使用。

@ApiClass

在多重類別 API 中，您可以使用 @ApiClass 為特定類別指定不同的屬性，藉此覆寫 @Api 設定中的對等屬性。如需這個註解的完整說明，請參閱「使用 @ApiClass 表示不同類別的屬性」。

@ApiReference

在多重類別 API 中，您可以使用 @ApiReference 提供註解繼承的替代方法。如需這個註解的完整說明，請參閱「使用 @ApiReference 繼承」一節。

@ApiResourceProperty

@ApiResourceProperty 可讓您控管在 API 中公開資源屬性的方式。您可以在屬性 getter 或 setter 上使用此方式，以便在 API 資源中省略該屬性。如果欄位設為不公開，您可以將這個註解用於欄位本身，使其在 API 中公開。此外，這個註解也可用來更改 API 資源中的屬性名稱。

必要匯入項目

如要使用這項功能，您需要匯入以下內容：

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

屬性

搭配 @ApiResourceProperty 的範例類別

以下程式碼片段示範屬性 getter 加註 @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();
}

在上述的程式碼片段中，@ApiResourceProperty 提供給 bin 屬性的 getBin getter，同時設定了 ignored 屬性，告知 Endpoints Frameworks 在 API 資源中省略這個屬性。

@ApiResourceProperty 也會套用至未包含 getter 或 setter 的不公開欄位 visible。使用這個註解會將欄位公開成 API 資源中的屬性。

在同一個程式碼片段中，@ApiResourceProperty 也會套用至不同的 getter (getFoobar)，它可以傳回 foobar 屬性的屬性值。這個註解中的 name 屬性會指示 Endpoints Frameworks 更改 API 資源中的屬性名稱。屬性值本身並不會改變。

在上述的範例程式碼片段中，Resp 物件的 JSON 表示法內容會與下列內容類似：

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

@ApiTransformer

@ApiTransformer 註解可以自訂某個類型如何透過與另一個類型之間的轉換，在 Endpoints 中公開，(指定的轉換器必須為 com.google.api.server.spi.config.Transformer)。

雖然指定轉換器時，建議對類別使用 @ApiTransformer 註解，但是您也可以在 @Api 註解的 transformer 屬性中另外指定自訂的轉換器。

必要匯入項目

如要使用這項功能，您必須匯入以下內容：

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

搭配 @ApiTransformer 的範例類別

以下程式碼片段示範使用 @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;
  }
}

系統會經由 BarTransformer 類別轉換這個類別。

Endpoints 轉換器類別範例

以下程式碼片段示範名為 BarTransformer 的範例轉換器類別。這是之前程式碼片段中，@ApiTransformer 所參考的轉換器：

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]));
  }
}

假設有一個物件含有類型 Bar 的屬性 bar，而沒有使用上述的轉換器，則物件將與下列內容類似：

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

如使用轉換器，物件將與下列內容類似：

{"bar": "1,2"}