AIP-165 按条件删除

编号	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、域行为和资源引用注解的指南。