AIP-214 资源过期
| 编号 | 214 |
|---|---|
| 原文链接 | AIP-214: Resource expiration |
| 状态 | 批准 |
| 创建日期 | 2018-06-19 |
| 更新日期 | 2018-06-19 |
客户经常希望设置某个资源或资源属性不再可用或生效的时间（例如轮转安全密钥）。目前，我们建议客户设定一个具体的“过期时间”，保存在 google.protobuf.Timestamp expire_time 域。然而，如果客户希望设定相对时间偏移量，而非具体的过期时间时，这会增加额外负担。
此外，现实中存在“生存时间”（通常缩写为TTL）概念，在使用自动生成的客户端库时，这个域的典型格式（以秒为单位的整数）可能导致较差的用户体验。
指南
- 希望表达过期时间的API 必须 使用名为
expire_time的google.protobuf.Timestamp域。 - 希望支持相对过期时间的API 必须 定义名为
expiration（或{something}_expiration）的oneof域，包含expire_time域和一个单独的google.protobuf.Duration域，名为ttl，并标记为只输入。 - API 必须 始终在
expire_time域中返回过期时间，并在查询资源时将返回的ttl域清空。 - 依赖特定“生存时间”语义的API（例如DNS必须将TTL表示为整数）*可以* 使用
int64 ttl域（此时 应当 提供先例说明）。
示例
message ExpiringResource {
// google.api.resource 和其他注解和域
oneof expiration {
// 资源过期时间的 UTC 时间戳。
// 输出时始终提供此域，无论输入发送了什么。
google.protobuf.Timestamp expire_time = 2;
// 仅输入。资源 TTL。
google.protobuf.Duration ttl = 3 [(google.api.field_behavior) = INPUT_ONLY];
}
}
理由
可能的备选方案
使用新的标准域 ttl
我们考虑过使用名为 ttl 的标准域，作为定义过期时间的替代方法。但这样做将要求 API 服务不断更新域，就像倒计时一样。这可能会在“读取-修改-写入”周期中引发问题，因为资源处理可能持续一段时间，并因此实际延长了资源的生命周期。
始终使用 expire_time
这是目前的状态，只有少数例外。此时我们可能会将计算 now + ttl = expire_time 放到客户端库。然而在命令行和使用 REST/JSON 时，这会带来一些令人沮丧的体验。保持现状通常是默认选项，但似乎许多客户希望能够定义相对过期时间，因为更简单，还能避免时区问题、错误的时钟时间以及其他一些愚蠢的错误。