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 是只输出域。