欄位遮罩

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 錯誤。