使用欄位遮罩更新

在 Google Ads API 中，更新作業會使用欄位遮罩完成。欄位遮罩清單 所有您想要變更更新的欄位，以及任何指定欄位 並忽略不在欄位遮罩中的 ，即使傳送至伺服器也是如此。

FieldMaskUtil

如要產生欄位遮罩，建議您使用內建欄位遮罩 這個公用程式可以隱藏許多具體細節 來自動遮蓋您對實體欄位所做的變更，進而自動遮蓋物件。

以下說明如何產生欄位遮罩，以便更新廣告活動：

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

程式碼會先建立一個空白的 Campaign 物件，然後將其資源名稱設為 通知 API 要更新的廣告活動。

本例在廣告活動中使用 client.field_mask.with 方法 包含更新內容的區塊在這個區塊結束時，公用程式會比較區塊後廣告活動的目前狀態，與區塊前廣告活動的初始狀態，並自動產生列舉已變更欄位的欄位遮罩。您可以將該欄位遮罩提供給 為 change 呼叫建構容器時的作業，如下所示：

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

如果需要進行複雜的作業，且 並精細控制每個步驟不過，在大部分的情況下， 更簡單的 Ruby 程式庫公用程式：

operation = client.operation.update_resource.campaign do |c|
  c.status = :PAUSED
  c.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

這個方法會自動建立新的空白廣告活動資源，並根據您在區塊中所做的變更，建構欄位遮罩、建構更新作業，然後傳回已填入 update 和 update_mask 的最終作業。您也可以將廣告活動傳遞至 campaign 方法， 同時指定廣告活動的起始狀態。這個模式適用於所有 支援更新作業的資源

手動建立遮罩

如要從頭開始建立欄位遮罩，而不需要使用任何程式庫公用程式，請先建立 Google::Protobuf::FieldMask，然後建立陣列，並填入您要變更的所有欄位名稱，最後將陣列指派給欄位遮罩的 path 欄位。

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

更新訊息欄位及其子欄位

MESSAGE 欄位可以有子欄位 (例如 MaximizeConversions，其中有三個：target_cpa_micros、cpc_bid_ceiling_micros 和 cpc_bid_floor_micros)，也可以沒有子欄位 (例如 ManualCpm)。

未定義子欄位的訊息欄位

如要更新尚未以任何子欄位定義的 MESSAGE 欄位，請使用 FieldMaskUtil 用於產生欄位遮罩，如前文所述。

訊息欄位及其定義的子欄位

更新不含子欄位定義的 MESSAGE 欄位時 明確設定該訊息的任何子欄位，您必須手動新增 每個可變動 MESSAGE 子欄位 (設為 FieldMask) 的方式類似 也就是從頭開始建立欄位遮罩的例子。

有一個常見的例子是更新廣告活動的出價策略時，並未設定任何相關設定 更新出價策略的任何欄位。以下範例 示範瞭如何更新廣告活動，以便採用 MaximizeConversions 出價策略 不必在出價策略中設定任何子欄位

在本範例中，使用 FieldMaskUtil 內建的比較工具 來達成預期目標

以下程式碼會產生包含 maximize_conversions 的欄位遮罩。 然而，Google Ads API 不允許這個行為， 意外清除欄位， FieldMaskError.FIELD_HAS_SUBFIELDS敬上 錯誤。

警告： 下列程式碼會產生錯誤。

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
# be included in a field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

以下程式碼示範如何正確更新廣告活動，以便使用 MaximizeConversions出價策略，但未設定任何子欄位。

成效： 下方程式碼已成功更新廣告活動出價策略。

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

正在清除欄位

部分欄位可明確清除。與前一個範例類似，您必須明確將這些欄位新增至欄位遮罩。舉例來說 採用「MaximizeConversions」出價策略的廣告活動，且獲得 「target_cpa_micros」欄位的值必須大於 0。

接著程式碼就會執行。不過，maximize_conversions.target_cpa_micros 不會加到欄位遮罩中，也不會變更 target_cpa_micros 欄位：

警告： 這個程式碼會導致錯誤。

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

下列程式碼示範如何正確清除 target_cpa_micros ] 欄位。MaximizeConversions

成功：下列程式碼會清除 target_cpa_micros。

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

請注意，即使程式碼的作用是 在 Google Ads API protocol buffers 中使用 optional。但由於 target_cpa_micros 並非 optional 欄位，因此「錯誤」程式碼不會更新出價策略來清除 target_cpa 欄位。

重點： 如果您的目的是清除某個欄位，最安全的方法就是 將該欄位明確加入欄位遮罩中。