AIP-164 软删除
| 编号 | 164 |
|---|---|
| 原文链接 | https://google.aip.dev/164 |
| 状态 | 批准 |
| 创建日期 | 2019-12-16 |
| 更新日期 | 2020-10-06 |
客户端需要使用软删除和恢复删除功能的原因有很多，一个非常突出的重要原因是：从错误中恢复。支持恢复删除的服务，让用户能够恢复意外删除的资源。
指南
API 可以 支持“恢复删除”功能，处理用户误删资源，需要恢复的情况。
如果资源支持恢复删除， Delete 方法 必须 将资源标记为已删除，而非从系统中完全移除。此时 Delete 方法 应当 返回更新后的资源，而非 google.protobuf.Empty 。
支持软删除的资源 应当 同时具有 delete_time 和 purge_time 域，如 AIP-148 所述。此外，如果资源包含 state 域（AIP-216），资源 应当 包含 DELETED 状态值。
恢复删除
支持软删除的资源 应当 提供 Undelete 方法：
rpc UndeleteBook(UndeleteBookRequest) returns (Book) {
option (google.api.http) = {
post: "/v1/{name=publishers/*/books/*}:undelete"
body: "*"
};
}
- HTTP 动词 必须 是
POST。 body子句 必须 是"*"。- 应答消息 必须 是资源本身。没有
UndeleteBookResponse。- 应答 应当 包含完整的资源，除非不可行。
- 如果恢复删除接口是耗时恢复删除，应答消息 必须 是
google.longrunning.Operation，解析为资源本身。
恢复删除请求消息
恢复删除方法实现了下面的常见请求消息模式：
message UndeleteBookRequest {
// The name of the deleted book.
// Format: publishers/{publisher}/books/{book}
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference).type = "library.googleapis.com/Book"];
}
- 必须 包含
name域，名字 应当 是name。 - 请求消息 不得 包含任何其他必需域， 不应 包含其他可选域，本文或其他AIP另有要求的除外。
耗时恢复删除
某些资源恢复删除所需的时间超过了常规 API 请求的合理范围。此时API 应当 使用耗时操作（AIP-151）：
rpc UndeleteBook(UndeleteBookRequest) returns (google.longrunning.Operation) {
option (google.api.http) = {
post: "/v1/{name=publishers/*/books/*}:undelete"
body: "*"
};
option (google.longrunning.operation_info) = {
response_type: "Book"
metadata_type: "OperationMetadata"
};
}
- 应答类型 必须 设置为资源（如果接口不是耗时操作，返回类型是资源自身）。
- 必须 设定
response_type和metadata_type域。
List和Get方法
默认情况下，软删除的资源 不应 出现在 List （AIP-132）应答中（ bool show_deleted 为 true 时除外）。对软删除资源的 Get （AIP-131）请求 应当 返回资源（而非 NOT_FOUND 错误）。
支持软删除资源的 API 可以 选择合理策略清除资源，包括在合理时间（如 30 天）后自动清除，允许用户设置过期时间（AIP-214），或无限期保留资源。无论选择哪种策略，API 应当 在文档中记录软删除资源被完全移除的时间。
声明友好资源
对声明式客户端，软删除资源的体验比硬删除资源要差：由于软删除资源的标识在调用自定义方法（恢复删除）之前不可重用，因此必须引入命令式客户端，或者手动编写代码适配自定义方法。
错误
如果用户没有权限访问资源，无论资源是否存在，服务 必须 返回 PERMISSION_DENIED （HTTP 403）错误。权限检查 必须 在存在性检测之前进行。
如果用户拥有权限，但目标资源不存在（从未创建或已被清除），服务 必须 返回 NOT_FOUND （HTTP 404）错误。
如果调用软删除 Delete 方法的用户拥有权限，但目标资源已被删除，服务 必须 在 allow_missing 设定为 true 时返回成功， 应当 在 allow_missing 设定为 false 时返回 NOT_FOUND （HTTP 404）错误。
如果调用 Undelete 的用户拥有权限，但目标资源未被删除，服务 必须 返回 ALREADY_EXISTS （HTTP 409）。
进一步阅读
- 关于
Delete标准方法，请参考 AIP-135。 - 关于耗时操作，请参考 AIP-151。
- 关于资源时效性验证（
etag），请参考 AIP-154。 - 关于变更验证（
validate_only），请参考 AIP-163。