当前位置：首页 > news >正文

AIP-161 域掩码

news 来源：原创 2025/6/8 21:46:25

编号	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_name
  repeated Author authors = 2;
}