支援的參數及傳回類型

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

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

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

  • java.lang.String
  • java.lang.Booleanboolean
  • java.lang.Integerint
  • java.lang.Longlong
  • java.lang.Floatfloat
  • java.lang.Doubledouble
  • 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 影響。方法參數只會在原始非轉換類型為注入類型時,才會被視為是注入類型。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁