AIP-165 按条件删除

news2025/3/14 11:25:57

编号	165
原文链接	https://google.aip.dev/165
状态	批准
创建日期	2019-12-18
更新日期	2019-12-18

有时API需要提供一种机制，按照一些过滤参数删除大量资源，而非提供待删除的各资源名字。

这是一个稀有的场景，用于用户一次性删除数千或更多资源的情况。此时，普通的批量删除模式（AIP-235）笨重低效。

指南

重要大多数API 应当仅使用删除（AIP-135）或批量删除（AIP-235）方法删除资源，不应实现按条件删除。因为删除通常是不可逆的，这类操作容易让用户意外丢失大量数据。

API 可以实现 Purge 方法，按过滤字符串删除大量资源。但应当仅在批量删除（AIP-235）模式无法实现预期目标时这么做。

rpc PurgeBooks(PurgeBooksRequest) returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books:purge"
    body: "*"
  };
  option (google.longrunning.operation_info) = {
    response_type: "PurgeBooksResponse"
    metadata_type: "PurgeBooksMetadata"
  };
}

接口名字必须以 Purge 开头，其余部分应当是待清除资源的复数形式。
请求消息必须与接口名字一致，并带有 Request 后缀。
应答类型必须是 google.longrunning.Operation （参考AIP-151），解析成一个名字与接口名字一致的消息，并带有 Response 后缀。
HTTP动词必须是 POST ， body 必须是 "*" 。
URI路径应当表示资源集合。
parent 字段应当包含在URI中。如果API支持跨多个上级资源删除，应当接受与AIP-159一致的 - 字符。

请求消息

Purge 方法实现了常见的请求消息模式：

message PurgeBooksRequest {
  // The publisher to purge books from.
  // To purge books across publishers, send "publishers/-".
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];

  // A filter matching the books to be purged.
  string filter = 2 [(google.api.field_behavior) = REQUIRED];

  // Actually perform the purge.
  // If `force` is set to false, the method will return a sample of
  // resource names that would be deleted.
  bool force = 3;
}

应当包含单一的 string parent 域，顶级资源除外。
- 域应当被注解为必需域。
- 域应当标识所引用的资源类型。
必须包含单一的 string filter 域，必须遵守和 List 方法（AIP-160）同样的语义。
- 应当被注解为必需域。
必须包含单一的 bool force 域。如果没有设定，API 必须返回将待删除资源数量和资源样本，而非实际执行删除。

应答消息

Purge 方法实现了常见的应答消息模式：

message PurgeBooksResponse {
  // The number of books that this request deleted (or, if `force` is false,
  // the number of books that will be deleted).
  int32 purge_count = 1;

  // A sample of the resource names of books that will be deleted.
  // Only populated if `force` is set to false.
  repeated string purge_sample = 2 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Book"
  }];
}

应当包含单一的 int32 purge_count 域，返回已删除（或待删除）资源数量。这个值可以是类似于AIP-158中 total_size 的近似值（若如此服务应当在文档中记录）。
应当包含 repeated string purge_sample 域。如果 force 设定为 false ，应当提供待删除资源名字样本。如果 force 设定为 true ，则此域不应返回值。
- 样本数量应当足够多，捕获显著错误。一个好的经验法则是100。API 应当在文档中记录样本大小，并应当说明这是数量上限（可能发送较少样本）。
- 样本可以是随机的，也可以是确定的（如第一个匹配的资源名字）。API 应当在文档中记录实现方法。
- 域应当标识所引用的资源类型。