使用欄位遮罩更新

在 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 方法，開始涵蓋更新的區塊。在這個區塊的結尾，公用程式會比較區塊後廣告活動的目前狀態與區塊前廣告活動的初始狀態，並自動產生列舉已變更欄位的欄位遮罩。建構變動呼叫時，您可以將該欄位遮罩提供給作業，如下所示：

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

下列程式碼示範如何正確清除 MaximizeConversions 出價策略中的 target_cpa_micros 欄位。

成功： 下列程式碼會清除 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 欄位。

重點： 如要清除欄位，最安全的方式是明確將該欄位新增至欄位遮罩。