字段掩码

Ad Manager REST API 对部分读取和写入操作使用字段掩码。这可以 通过限制传输的数据量来提升性能。字段掩码 以逗号分隔的字段名称列表表示。例如：

startTime,endTime,targeting.geoTargeting

读取掩码

读取掩码用于控制 API 响应中存在哪些字段。您可以设置 通过以下两种方式读取请求中的掩码：

1. fields 查询参数：

   curl https://admanager.googleapis.com/v1/networks/123456/adUnits?fields=adUnits,nextPageToken,totalSize
   

2. X-Goog-FieldMask HTTP 标头：

   curl -H "X-Goog-FieldMask: adUnits,nextPageToken,totalSize" \
       https://admanager.googleapis.com/v1/networks/123456/adUnits
   

。

注意： 字段掩码字符串同时支持 camelCase 和 snake_case。

默认读取掩码

对于开销非常大的字段，某些 API 方法包含默认字段掩码 返回。列表方法就是一个例子。默认情况下，它们不包含 totalSize 字段。

必须在字段掩码中通过名称或 * 通配符。

更新遮罩

更新掩码控制在更新中更改哪些字段 (PATCH) 请求。设置更新掩码后，系统只会更新掩码中的字段 无论请求正文中设置了哪些字段。

更新掩码设置为查询参数。例如：

curl -X PATCH https://admanager.googleapis.com/v1/networks/1234/order/4567?updateMask=displayName

字段遍历

字段掩码可以使用 . 字符来指定实体中的字段 遍历。该语法与 过滤器。

字段掩码始终与响应对象相关。例如， 读取 LineItem 可能包含 primaryGoal.units。相应的掩码 商家信息 LineItems 为 lineItems.primaryGoal.units。

您既可以指定整个字段，也可以指定它的某个子字段。两者都有 primaryGoal 和 primaryGoal.units 有效。

这也适用于重复字段。LineItem 字段掩码为 creativePlaceholders.size 有效且仅包含 size 字段 CreativePlaceholder

注意 ：字段掩码不允许访问重复 字段。这会导致 INVALID_ARGUMENT 错误。

通配符

警告 ：在更新掩码中使用通配符不向前兼容。通过 通配符会清除您的客户端未知的所有字段。

字段掩码支持 * 字符，该字符指示消息中的所有字段。 以下示例演示了列出 Orders。此方法具有默认读取掩码，该掩码 不包含 total_size 字段。

示例	含义
*	包括所有字段，包括 total_size
orders	仅包含 orders 字段及其所有子字段
orders.*	仅包含 orders 字段及其所有子字段

字段无效

如果字段掩码引用的值不存在，API 将响应 并显示 INVALID_ARGUMENT 错误。