| 編號 | 161 |
|---|---|
| 原文鏈接 | AIP-161: Field masks |
| 狀態 | 批準 |
| 創建日期 | 2021-03-01 |
| 更新日期 | 2021-03-01 |
在（使用AIP-134的Update或類似方法）更新資源時，通常需要明確指定哪些域需要更新。服務可以忽略另外的域，即使用戶發送了值。
定義一種掩碼格式，為每個API處理更具體需求的方案雖然吸引人。但考慮到掩碼需求不斷變化，明智的做法是使用一種結構化語法，可以透明地進行更新，無需等待界面或客戶端升級。
指南
域名字的掩碼稱為“域掩碼”。表示域掩碼的域?必須?使用?google.protobuf.FieldMask?類型。域掩碼在Update請求（AIP-134）中很常見。
域掩碼?必須?始終相對于資源：
警告?將讀掩碼作為請求消息中獨立域（如?
google.protobuf.FieldMask read_mask?）的方案?已廢棄?。
message UpdateBookRequest {// The book to update.//// The book's `name` field is used to identify the book to update.// Format: publishers/{publisher}/books/{book}Book book = 1 [(google.api.field_behavior) = REQUIRED];// The list of fields to update.// Fields are specified relative to the book// (e.g. `title`, `rating`; *not* `book.title` or `book.rating`).google.protobuf.FieldMask update_mask = 2;
}
讀寫一致性
如果使用域掩碼，其讀寫行為?必須?自洽：
- 如果用戶使用某個掩碼更新資源，然后使用相同掩碼讀取同一資源，服務?必須?返回完全相同的數據。
- 例外：只輸出域。
- 類似地，使用某個掩碼讀取資源，然后用收到數據和相同掩碼更新資源的請求?必須?不產生實際修改。
注意?這意味著任何對讀請求或寫請求有效的掩碼，?必須?同時對兩者都有效。
設定域掩碼
域掩碼?必須?允許使用?.?字符遍歷指定消息結構中的域。
域掩碼始終是相對于資源的，資源直接包含的域（如?title?，?rating?）不需要遍歷。遍歷用在資源包含消息的時候（如?author.given_name?）。
注意?用戶?必須?可以指定整個消息域，或消息域的子域：?
author?和?author.given_name?都有效。
Map域
域掩碼?可以?支持使用?.?字符遍歷指定Map中的域，只要Map的鍵是字符串或整數。
域掩碼?應當?支持字符串鍵，處理鍵不符合域掩碼語法的情況。字符串鍵使用反引號包圍。
message Book {// The name of the book.// Format: publishers/{publisher}/books/{book}string name = 1;// Reviews for the back cover. The key is the author of the review,// and the value is the text of the review.//// Valid field masks: reviews, reviews.smith, reviews.`John Smith`map<string, string> reviews = 2;
}
通配符
域掩碼?可以?允許在重復域或Map上使用?*?字符，指示集合元素的特定子域：
message Book {option (google.api.resource) = {type: "library.googleapis.com/Book"pattern: "publishers/{publisher}/books/{book}"};// The name of the book.// Format: publishers/{publisher}/books/{book}string name = 1 [(google.api.field_behavior) = IDENTIFIER];// The author or authors of the book.// Valid field masks: authors, authors.*.given_name, authors.*.family_name// Invalid field masks: authors.0, authors.0.given_namerepeated Author authors = 2;
}
注意?域掩碼?不得?允許通過索引訪問重復域的特定元素。如果收到這種請求，?必須?返回?
INVALID_ARGUMENT?錯誤。
只輸出域
如果用戶（使用通配符或指定包含只輸出域的消息）間接在更新掩碼中包含了只輸出域，服務?必須?忽略隨請求輸入的任何只輸出域，即使請求要求清理或修改它們。
如果用戶在更新掩碼中直接設定了只輸出域，服務?必須?忽略隨請求輸入的只輸出域，即使請求要求清理或修改它們，以便支持同一個域掩碼同時用于輸入和輸出。
無效的域掩碼條目
讀取數據時，域掩碼?可以?忽略指向不存在的值的條目（無論是域不存在，還是服務認定的無效Map鍵）。
寫入數據時，如果條目指向不存在的值，服務?應當?返回?INVALID_ARGUMENT?錯誤。然而服務?可以?允許刪除請求。
修訂記錄
- 2023-10-18?更新關于更新掩碼中存在只輸出域的指南。
- 2023-07-17?將?
update_mask?指南移至AIP-134。
)
