AIP-148 标准域
| 编号 | 148 |
|---|---|
| 原文链接 | AIP-148: Standard fields |
| 状态 | 批准 |
| 创建日期 | 2020-10-06 |
| 更新日期 | 2020-10-06 |
一些概念在任何API集合中都很常用。对于这些概念，使用统一的标准域名字和行为来表达它们，是非常有用的。
指南
标准域 应当 用于描述其相应概念， 不应 用于任何其他目的。
资源名字和标识
name
每个资源 必须 有一个 string name 域，记录资源名字（AIP-122），它 应当 是资源的第一个域。
注意
_name后缀 不应 用于描述其他类别的名字，本AIP中另有说明的除外。
parent
string parent 域表示集合的上级资源的资源名字， 应当 在大多数 List （AIP-132）和 Create （AIP-133）请求中使用。
其他名字
display_name
string display_name 域 必须 是一个可变的、用户可设定域，用户可以提供一个用于界面的易于阅读的名字。声明友好资源 应当 包含这个域。
显示名字 不应 存在唯一性要求， 应当 限制不超过63个字符。
title
string title 域 应当 是实体的正式名字，例如公司名字。它是 string display_name 的一个正式的变体。
given_name
string given_name 域 必须 指代人类或动物的名（译注：“姓名”的名）。资源 不得 使用 first_name 表示这个概念，因为在许多文化中，名不会排在姓的前面。
family_name
string family_name 域 必须 指代人类或动物的姓。资源 不得 使用 last_name 表示这个概念，因为在许多文化中，姓不会排在姓名最后。
时间戳
create_time
仅输出域 google.protobuf.Timestamp create_time 必须 表示资源创建时的时间戳。 可以 是创建操作开始时间或完成时间。声明友好资源 应当 包含这个域。
update_time
只输出域 google.protobuf.Timestamp update_time 必须 表示资源最近一次修改时的时间戳。用户对资源所做的任何改变 必须 更新此值；服务内部对资源所做的改变 可以 更新此值。声明友好资源 应当 包含此域。
delete_time
只输出域 google.protobuf.Timestamp delete_time 必须 表示资源软删除时的时间戳。 可以 对应于用户请求删除的时间，或服务成功软删除资源的时间。如果资源没有被软删除， delete_time 域 必须 为空。
支持软删除的资源（AIP-164） 应当 提供此域。
expire_time
google.protobuf.Timestamp expire_time 域 应当 表示给定资源或资源属性不可用或失效的时间（例如轮换安全密钥）。 可以 用于AIP-214中描述的类似形式的失效时间。
服务 可以 提供不太精确的 expire_time 值，但资源 不得 在该时间之前失效。
purge_time
google.protobuf.Timestamp purge_time 域 应当 表示软删除的资源计划从系统中清除的时间（参考AIP-164）。 可以 用于AIP-214中描述的类似形式的失效时间。支持软删除的资源 应当 包含此域。
服务 可以 提供一个不太精确的 purge_time 值，但系统 不得 在该时间之前清除资源。
标注
为了存储少量的任意数据， 可以 添加一个 map<string, string> annotations 域。
annotations 域 必须 使用Kubernetes限制来保证传输兼容性， 应当 使用点（“.”）分隔命名空间注释键，防止工具互相干扰。
可能存储在标注域中的信息示例包括：
- 对于CI/CD，用于流转的流水线运行实例标识符，或版本控制标识符。
注意
annotations与其他形式的标签不同。标签可以供服务器端策略使用，例如IAM条件。标注的目的是允许客户端工具记录自己的状态信息，而不需要数据库。
已知字符串域
IP地址
表示IP地址的域 必须 符合以下要求：
- 使用类型
string。 - 使用名字
ip_address或以_ip_address结尾。如resolved_ip_address。 - 表明IP地址版本格式，使用
IPV4、IPV6，或者在同时支持二者时，使用IPV4_OR_IPV6（参考AIP-202）。
uid
只输出域 string uid 指的是系统分配的资源唯一标识符。如果使用此域， 它 必须 是UUID4， 必须 通过 UUID4 格式扩展表明格式（参考AIP-202）。声明友好资源 应当 包含此域。
进一步阅读
- 关于标准化代号，请参考AIP-143。
- 关于
etag域，请参考AIP-154。 - 关于
request_id域，请参考AIP-155。 - 关于
filter域，请参考AIP-160。 - 关于资源修订相关域，请参考AIP-162。
- 关于
validate_only域，请参考AIP-163。 - 关于软删除和恢复删除相关域，请参考AIP-164。
理由
已知字符串域
一些域用来表示非常明确的概念，或者带有严谨语义的工件。对于这些域，提供统一API接口很重要。促进了API消费者工具和文档的优化改进工作，同时提供了跨平台的统一用户体验。
历史
在2023年7月之前，软删除资源的 purge_time 也称为 expire_time 。引入 purge_time 可以减少用户困惑。
修订记录
- 2023-10-05 引入已知字符串域，包括IP地址和
uid。 - 2023-08-14 从AIP-128引入术语
annotations。 - 2023-07-13 引入术语
purge_time。 - 2021-04-06 要求
uid和delete_time是只输出域。