tommwq.work/aip

AIP-165 按条件删除

· [tommwq@126.com]
编号 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 应当 在文档中记录实现方法。
    • 域 应当 标识所引用的资源类型。

注意 请求 必须 包含 force 域，即使缺少 purge_count 和 purge_sample 域。

修订记录

  • 2022-06-02 更改后缀描述，消除多余的"-"。
  • 2020-10-29 扩展关于HTTP、域行为和资源引用注解的指南。