欄位遮罩

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

FieldMasks 公用程式

如要產生欄位遮罩，建議您使用內建欄位遮罩 水電瓦斯費 (FieldMasks), 可讓您運用修改的物件產生欄位遮罩，而非建構物件 從頭開始設計

以下是更新廣告活動的範例：

my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    status => PAUSED,
    networkSettings =>
      Google::Ads::GoogleAds::V17::Resources::NetworkSettings->new({
        targetSearchNetwork => "false"
      })
    });

my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

這個範例會先設定資源名稱來建立 Campaign 物件 使用 ResourceNames 公用程式，讓 API 知道 要更新的廣告活動。

本範例使用 FieldMasks::all_set_fields_of()敬上 方法，以自動產生列舉所有欄位遮罩的欄位遮罩 設定欄位。然後，您可以將傳回的遮罩直接傳遞至更新呼叫。

FieldMasks::all_set_fields_of() 是相當便利的方法 FieldMasks::field_mask()。 可比較傳遞的物件與相同類別的空白物件。在 上方程式碼也可使用

field_mask(Google::Ads::GoogleAds::V17::Resources::Campaign->new({}), $campaign)

而不是 all_set_fields_of($campaign)。

手動建立遮罩

如要從頭建立欄位遮罩，您必須先建立 Google::Ads::GoogleAds::Common::FieldMask敬上 物件，然後填入採用所有欄位名稱的陣列參照 並將陣列參照指派給欄位遮罩的 paths 欄位中。

my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
    paths => ["status", "name"]
  });

更新物件欄位及其子欄位

物件欄位可包含子欄位 (例如 MaximizeConversions，其中包含三個： target_cpa_micros、cpc_bid_ceiling_micros 和 cpc_bid_floor_micros)；或 但沒有任何關係 (例如 ManualCpm)。

未定義子欄位的物件欄位

Perl 中的物件欄位相當於用戶端中的 protobuf MESSAGE 於 gRPC 上執行的程式庫更新未定義的物件欄位時 包含任何子欄位，請使用 FieldMasks 公用程式產生欄位遮罩，如 相同。

含有已定義子欄位的物件欄位

更新未明確透過子欄位定義的物件欄位時 設定該訊息的任何子欄位，您必須手動新增 可變動的物件子欄位至 FieldMask，與上述範例類似 可從頭開始建立欄位遮罩

有一個常見的例子，就是更新廣告活動的出價策略時，並未設定任何 新出價策略欄位的部分。以下範例說明如何 更新廣告活動 MaximizeConversions 出價策略 不必在出價策略中設定任何子欄位

在這種情況下，請使用 all_set_fields_of() 和 field_mask() FieldMasks 公用程式無法達成預期目標。

以下範例產生的欄位遮罩 maximize_conversions。但 Google Ads API 不允許這個行為 可避免不小心清除欄位，並產生 FieldMaskError.FIELD_HAS_SUBFIELDS敬上 錯誤。

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

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V17::Resources::MaximizeConversions->new()
    });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask will include 'maximize_conversions',
# which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty object fields cannot
# be included in a field mask.
my $response = $api_client->CampaignService()->mutate({
    customerId => $customer_id,
    operations => [$campaign_operation]
  });

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

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

# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    )
  });

# Creates a field mask from the existing campaign and adds all of the fields
# on the MaximizeConversions bidding strategy to the field mask. Because these
# fields are included in the field mask but excluded from the campaign object,
# the Google Ads API will set the campaign's bidding strategy to a
# MaximizeConversions object with none of its subfields set.
# Only include 'maximize_conversions.target_cpa_micros' in the field mask
# as it is the only mutable subfield on MaximizeConversions when used as a
# standard bidding strategy.
#
# Learn more about standard and portfolio bidding strategies here:
# https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
my $field_mask = all_set_fields_of($campaign);
push @{$field_mask->{paths}}, "maximize_conversions.target_cpa_micros";

# Creates an operation to update the campaign with the specified fields.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => $field_mask
  });

正在清除欄位

只要將欄位新增至欄位遮罩中，即可明確清除欄位，如下所示 ，或是將欄位設為空白或未定義的值。例如： 假設您有一個廣告活動採用「MaximizeConversions」出價策略 且「target_cpa_micros」欄位設定的值大於 0。

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

# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
  Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V17::Resources::MaximizeConversions->new({
      targetCpaMicros => 0
    })
  });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask, which will include 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

請注意，如要清除含有巢狀子欄位的欄位，您必須逐一清除各個欄位。 如 物件欄位所示， 子欄位。