編號	156
原文鏈接	AIP-156: Singleton resources
狀態	批準
創建日期	2019-05-12
更新日期	2024-04-15

API有時需要表示在任意上級資源中，始終只存在一個實例的資源。常見的例子是配置對象。

指南

API?可以?定義?單例資源?。單例資源?必須?始終隨上級資源而存在，每個上級資源擁有唯一的單例資源。

例如：

message Config {option (google.api.resource) = {type: "api.googleapis.com/Config"pattern: "users/{user}/config"singular: "config"plural: "configs"};// additional fields including name
}

Config?單例資源具有以下接口：

rpc GetConfig(GetConfigRequest) returns (Config) {option (google.api.http) = {get: "/v1/{name=users/*/config}"};
}rpc UpdateConfig(UpdateConfigRequest) returns (Config) {option (google.api.http) = {patch: "/v1/{config.name=users/*/config}"body: "config"};
}

• 單例資源?不得?擁有用戶設定或系統生成的標識；其資源名字包含上級資源名字，后接一個固定部分。
  • 示例：?users/1234/config
• 單例資源始終使用單數形式。
  • 示例：?users/1234/thing
• 單例資源定義?必須?提供?singular?和?plural?域（見上例）。
• 單例資源?可以?作為其他資源的上級資源。
• 單例資源?不得?定義Create或Delete標準方法。單例資源在其上級資源創建或刪除時自動創建或刪除。
• 單例資源?應當?定義Get和Update方法，?可以?按需提供自定義方法。
  • 如果資源的所有域都是只輸出域，單例資源?不得?定義Update方法。
• 單例資源?可以?定義List方法，但?必須?遵守AIP-159。見下例。
  • 用來表示集合的路徑模式中的最后一段?應當?使用單例資源的?plural?形式，如?/v1/{parent=users/*}/configs?。
  • 如果按照AIP-159提供了上級資源標識而非連字符?-?，服務?應當?返回包含與指定上級資源對應的單例資源集合。

rpc ListConfigs(ListConfigsRequest) returns (ListConfigsResponse) {option (google.api.http) = {get: "/v1/{parent=users/*}/configs"};
}message ListConfigsRequest {// To list all configs, use `-` as the user id.// Formats:// * `users/-`// * `users/{user}`//// Note: Specifying an actual user id will return a collection of one config.// Use GetConfig instead.string parent = 1 [(google.api.resource_reference).child_type = "api.googleapis.com/Config"];// other standard pagination fields...
}

理由

支持標準List方法

雖然單例資源本身不是集合中的元素，但它們可以被視為上級資源集合的一部分。上級資源與單例資源的一對一對應關系意味著每個上級資源都有一個單例資源，在與跨集合讀取模式結合時，自然的產生了一些基于集合的方法。由于間接依賴于上級資源集合，單例資源可以作為集合提供給API消費者。此外，在此類方法中將單例資源組成偽集合，可以在將來擴展到實際集合上，彌補單例模式不足。

包含?plural?定義

雖然單例資源在定義上是單數，但在某些情況下，也可能以復數形式出現。例如，服務支持標準List方法（如本文所描述）。因此最好提前聲明單例資源類型的復數形式，以免需要時找不到。

修訂記錄

• 2024-04-15?單例資源必須提供?singular?和?plural?。
• 2023-08-10?添加標準?List?方法支持。
• 2023-07-26?闡明只讀單例資源不應具有?Update?方法。
• 2021-11-02?添加示例消息，說明上級資源資格。
• 2021-01-14?將示例從?settings?改為?config?，提高清晰程度。