AIP-156 单例资源

编号	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消费者。此外，在此类方法中将单例资源组成伪集合，可以在将来扩展到实际集合上，弥补单例模式不足。