支援的參數及傳回類型

此頁列出了各種資料類型，您可以將這些資料做為後端 API 方法的路徑或查詢參數中的 API 參數，並可做為方法傳回類型或要求主體類型。

路徑與查詢參數支援的類型

以下列出路徑與查詢參數支援的類型：

  • java.lang.String
  • java.lang.Boolean 和 boolean
  • java.lang.Integer 和 int
  • java.lang.Long 和 long
  • java.lang.Float 和 float
  • java.lang.Double 和 double
  • java.util.Date
  • com.google.api.server.spi.types.DateAndTime
  • com.google.api.server.spi.types.SimpleDate
  • 任何enum
  • 任何陣列或java.util.Collection。不支援其他類型的陣列或集合。

如要將參數指定為路徑或查詢參數，請將參數註解為 @Named。 例如：

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

路徑參數

路徑參數是 @ApiMethod 註解的 path 屬性中包含的方法參數。如果未指定 path，系統會自動將未標註 @Nullable 或 @DefaultValue 的參數新增至路徑，做為路徑參數。例如：

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

如要手動新增參數至 path，請在路徑中的 {} 標記中加入參數名稱。手動新增到 path 的參數無法使用 @Nullable 或 @DefaultValue 註解。例如：

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

查詢參數

查詢參數是未包含在 @ApiMethod 註解的 path 屬性中的方法參數。請注意，可選的參數 (包含帶有 @Nullable 或 @DefaultValue 註解的參數) 永遠不會自動新增至 path，因此若沒有指定 path，它們會自動查詢參數。 例如：

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

如果指定 path，則可以不將參數納入 path 中，以使參數成為查詢參數。例如：

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

注入類型

注入類型是由 Cloud Endpoints Frameworks 處理的特殊處理類型。如果將此類型用作方法參數，則不會將其做為 API 的一部分。此時參數將由 Endpoints Frameworks 填入。

注入類型如下所示：

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

實體類型

在 Endpoints Frameworks 文件中，「實體類型」與「Java Beans」同義。您用於 API 所定義的類別必須：

  • 有一個沒有引數的公共建構函式。
  • 使用 getter 和 setter 控制對私有屬性的存取權。 此外，每個 setter 只能使用一個參數。

通常，實體類型也會執行序列化，但並沒有要求使用 Endpoints Frameworks。

不要將 @Named 註解用於實體類型的參數。

要求主體

當您在方法中將實體類型做為參數傳遞時，實體類型中的屬性將對應到要求主體中的 JSON 欄位。您的方法必須僅包含一個實體類型參數。例如：

public Resource set(Resource resource) { … }

您可以在方法中納入非實體類型參數和實體類型參數。例如：

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

在上述範例中，message 參數中的屬性對應到要求主體中的 JSON 欄位。@Nullable 註解表示 n 參數為選用，因此會做為查詢參數傳遞。

回應物件

方法傳回的値必須是以下其中之一：

  • 實體類型
  • 一般類型
  • CollectionResponse (com.google.api.server.spi.response.CollectionResponse) 或是 CollectionResponse 的子類別

回應物件中的 JSON 欄位是從傳回值的屬性對應的。

@ApiTransformer 對類型的影響

如果使用 @ApiTransformer，您需要瞭解類型如何受到轉換的影響。

@ApiTransformer 和參數類型

使用 @ApiTransformer 時，結果方法參數是否被視為「參數類型」取決於轉換結果，而非「原始類型」。如果將類型轉換為參數類型，方法參數將會被視為 API 參數，且必須使用 @Named 註解。

@ApiTransformer 和實體類型

同樣地，方法參數或傳回類型是否被視為「實體類型」取決於轉換的結果，而非原始類型。如果將類型轉換為參數類型，該類型可以使用為傳回類型，而如果將該類型使用為方法參數，因為會視為實體類型，所以無法使用 @Named 註解。

@ApiTransformer 和注入類型

注入類型不受 @ApiTransformer 影響。方法參數只會在原始非轉換類型為注入類型時，才會被視為是注入類型。