当前位置：首页 > article >正文

AIP-162 资源修订

article 2025/3/10 14:53:14

编号	162
原文链接	AIP-162: Resource Revisions
状态	草案
创建日期	2023-09-01
更新日期	2019-09-17

一些API需要保留资源修订历史，用户可以推断资源在历史上的状态。这有几个原因：

用户希望能够回滚到先前的修订，或者比较与先前修订的差异。
API创建的数据可能是从某个时间点的资源派生出来的。此时需要为资源创建快照，供以后参考。

注意我们使用“修订”（revision）指代特定资源的历史参考，并有意避免使用“版本”（version）一词，后者指的是API整体的版本。

指南

API 可以存储资源的修订历史。用途示例包括：

需要通过API发布资源的历史修订。避免客户自己编写API，存储和检索修订历史的成本。
资源依赖于另外一个资源的历史修订。
需要表示资源状态的变化历史。

实现带有修订历史的资源的API时，应当将资源修订抽象为资源的内嵌集合。有时修订集合也可以是顶级集合，例外情况包括：

如果资源修订的生命周期比资源自身更长。换句话说，资源修订在资源删除后仍然存在。

message BookRevision {
  // The name of the book revision.
  string name = 1;

  // The snapshot of the book
  Book snapshot = 2
    [(google.api.field_behavior) = OUTPUT_ONLY];

  // The timestamp that the revision was created.
  google.protobuf.Timestamp create_time = 3
    [(google.api.field_behavior) = OUTPUT_ONLY];

  // Other revision IDs that share the same snapshot.
  repeated string alternate_ids = 4
    [(google.api.field_behavior) = OUTPUT_ONLY];
}

消息必须被注解为资源（AIP-123）。
消息名字必须命名为 {ResourceType}Revision 。
资源修订必须包含类型为资源自身，名字为 snapshot 的域。
- snapshot 的值必须是资源自身在修订创建时的状态。
资源修订必须包含 create_time 域（参考AIP-142）。
资源修订可以包含重复域 alternate_ids ，包含识别修订的资源标识别名列表（例如 latest ）。

创建修订

根据资源的不同，不同的API可能采用不同策略：

资源自身发生变化时创建修订
重要系统状态变化时创建修订
收到特定请求时创建新修订

API 可以使用这些策略中的任何一种。API 必须在文档中记录修订创建策略。

修订的资源名字

引用资源的特定修订时，子集合名字必须是 revisions 。资源修订名字的格式为 {resource_name}/revisions/{revision_id} 。例如：

publishers/123/books/les-miserables/revisions/c7cfa2a8

服务器设定的别名

服务可以保留特定标识作为别名（如 latest ）。它们是只读的，由服务器管理。

GET /v1/publishers/{publisher}/books/{book}/revisions/{revision_id}

如果存在 latest 标识，必须表示最近创建的修订。 publishers/{publisher}/books/{book}/revisions/latest 和 publishers/{publisher}/books/{book} 的内容可能不同，最新修订可能与资源的当前状态不同。

用户设定的别名

API 可以提供一种机制，允许用户通过自定义方法“alias”为修订设定别名：

rpc AliasBookRevision(AliasBookRevisionRequest) returns (Book) {
  option (google.api.http) = {
    post: "/v1/{name=publishers/*/books/*/revisions/*}:alias"
    body: "*"
  };
}

message AliasBookRevisionRequest {
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "library.googleapis.com/BookRevision"
    }];

  // 要别名的修订ID，例如 ~CURRENT~ 或语义修订。
  string alias_id = 2 [(google.api.field_behavior) = REQUIRED];
}

请求消息必须有 name 域：
- 必须被注解为必需域。
- 必须标识其引用的资源类型。
请求消息必须有 alias_id 域：
- 必须被注解为必需域。
如果用户使用现有 alias_id 调用方法，方法必须成功执行，将别名指向所要求的修订。这允许用户编写针对特定别名（如 published ）的代码，修订也可以在不修改代码的情况下变更。

回滚

具有修订历史的资源的一个常用场景是能够回滚到特定修订。API 应当通过自定义方法 Rollback 处理这个问题：


rpc RollbackBook(RollbackBookRequest) returns (BookRevision) {
  option (google.api.http) = {
    post: "/v1/{name=publishers/*/books/*/revisions/*}:rollback"
    body: "*"
  };
}

必须使用 POST HTTP 动词。
应当返回资源修订。


message RollbackBookRequest {
  // 书籍应回滚到的修订。
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "library.googleapis.com/BookRevision"
    }];
}