AIP-214 资源过期

客户经常希望设置某个资源或资源属性不再可用或生效的时间（例如轮转安全密钥）。目前，我们建议客户设定一个具体的“过期时间”，保存在 google.protobuf.Timestamp expire_time 域。然而，如果客户希望设定相对时间偏移量，而非具体的过期时间时，这会增加额外负担。

此外，现实中存在“生存时间”（通常缩写为TTL）概念，在使用自动生成的客户端库时，这个域的典型格式（以秒为单位的整数）可能导致较差的用户体验。

指南

1. 希望表达过期时间的API 必须 使用名为 expire_time 的google.protobuf.Timestamp域。
2. 希望支持相对过期时间的API 必须 定义名为 expiration （或 {something}_expiration ）的 oneof 域，包含 expire_time 域和一个单独的google.protobuf.Duration域，名为 ttl ，并标记为只输入。
3. API 必须 始终在 expire_time 域中返回过期时间，并在查询资源时将返回的 ttl 域清空。
4. 依赖特定“生存时间”语义的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 时，这会带来一些令人沮丧的体验。保持现状通常是默认选项，但似乎许多客户希望能够定义相对过期时间，因为更简单，还能避免时区问题、错误的时钟时间以及其他一些愚蠢的错误。