此頁列出了各種資料類型,您可以將這些資料做為後端 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
影響。方法參數只會在原始非轉換類型為注入類型時,才會被視為是注入類型。