編號	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、域行為和資源引用注解的指南。