AIP-128 声明友好接口

许多服务需要与常见的DevOps工具交互，特别是创建和管理可网络寻址资源（如虚拟机、负载均衡器、数据库实例等）的工具。这些工具采用“配置即代码”原则：用户设定一个完整的目标状态，工具负责执行必要的操作，实现用户设定的规范。

这些工具是 声明式 的：不指定具体要执行的操作，而是指定期望的目标。操作是根据当前状态与目标状态之间的差异推导出来的。

此外，流行的DevOps工具数量众多，每年又会出现大量的新工具。将数百种资源类型与多个工具进行集成，需要统一接口，以便自动执行集成工作。

指南

资源

声明友好资源 必须 始终使用标准方法管理资源生命周期，这将允许工具广泛支持这些资源，同时也符合声明友好指南的其他要求（参考进一步阅读）。

声明友好资源 应该 指明其遵守声明友好风格：

message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
    style: DECLARATIVE_FRIENDLY
  };

  // Name and other fields...
}

协调

如果更新资源需要较长时间（超过几秒），资源 应该 包含一个 bool reconciling 域，告知更改正在进行。这个域 必须 是仅输出的。

如果资源的当前状态与用户预期的状态不一致，并且系统正在协调处理，资源 必须 将 reconciling 域设置为 true ，无论开始协调的根本原因是用户操作或系统动作。

注意： 处理 GET 请求的服务 必须 返回资源的当前状态（而非预期状态）。

进一步阅读

关于声明友好接口存在大量更严格的指南，因为它关注于对资源的自动化操作。下面的列表是其他AIPs中关于声明友好接口指南的汇总：

• 资源 不应 使用自定义方法：参考AIP-136。
• 资源 必须 使用 UPDATE 方法处理重复域：参考AIP-144。
• 资源 必须 包含特定的标准域：参考AIP-148。
• 资源 必须 具有 etag 域：参考AIP-154。
• 资源 应该 提供验证更改的方法：参考AIP-163。
• 资源 不应 实现软删除。如果资源标识不能重复使用，资源 必须 实现软删除和撤销删除RPC：参考AIP-164。

注解

参考AIP-148注解。

修订记录

• 2023-07-13 将 annotations 移动到AIP-148。
• 2023-06-17 删除关于平面的定义，移动到AIP-111。
• 2023-05-11 删除对resource_id域的“必须”要求，该要求已移动到通用的“必须”规范中。