Mặt nạ trường

Trong Google Ads API, các bản cập nhật được thực hiện bằng cách sử dụng một mặt nạ trường. Mặt nạ trường liệt kê tất cả các trường mà bạn dự định thay đổi bằng nội dung cập nhật và mọi trường được chỉ định không có trong mặt nạ trường đều bị bỏ qua, ngay cả khi được gửi đến máy chủ.

Tiện ích FieldMasks

Cách được đề xuất để tạo mặt nạ trường là sử dụng tiện ích mặt nạ trường tích hợp sẵn của chúng tôi (FieldMasks). Tiện ích này cho phép bạn tạo mặt nạ trường từ một đối tượng đã sửa đổi thay vì tạo mặt nạ trường từ đầu.

Sau đây là ví dụ về cách cập nhật một chiến dịch:

use Google::Ads::GoogleAds::Utils::FieldMasks qw(all_set_fields_of field_mask);

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

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

Ví dụ này trước tiên tạo một đối tượng Campaign bằng cách đặt tên tài nguyên của đối tượng đó bằng tiện ích ResourceNames, để API biết chiến dịch nào đang được cập nhật.

Ví dụ này sử dụng phương thức FieldMasks::all_set_fields_of() trên chiến dịch để tự động tạo một mặt nạ trường liệt kê tất cả các trường được đặt. Sau đó, bạn có thể truyền trực tiếp mặt nạ được trả về vào lệnh gọi cập nhật.

FieldMasks::all_set_fields_of() là một phương thức thuận tiện cho FieldMasks::field_mask(). Phương thức này so sánh đối tượng được truyền với một đối tượng trống thuộc cùng một lớp. Trong mã trước đó, bạn cũng có thể sử dụng:

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

thay vì all_set_fields_of($campaign).

Tạo mặt nạ theo cách thủ công

Để tạo một mặt nạ trường từ đầu, trước tiên, bạn tạo một đối tượng Google::Ads::GoogleAds::Common::FieldMask, sau đó tạo một tham chiếu mảng được điền tên của tất cả các trường mà bạn dự định thay đổi, rồi cuối cùng chỉ định tham chiếu mảng cho trường paths của mặt nạ trường:

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

Cập nhật các trường đối tượng và trường con của chúng

Các trường đối tượng có thể có các trường con (chẳng hạn như MaximizeConversions, bao gồm các trường con như target_cpa_micros) hoặc không có trường con nào (chẳng hạn như ManualCpm).

Các trường đối tượng không có trường con được xác định

Trường đối tượng trong Perl tương đương với MESSAGE protobuf trong các thư viện ứng dụng chạy trên gRPC. Khi cập nhật một trường đối tượng không được xác định bằng bất kỳ trường con nào, hãy sử dụng tiện ích FieldMasks để tạo một mặt nạ trường, như mô tả trong phần trước.

Các trường đối tượng có trường con được xác định

Khi cập nhật một trường đối tượng được xác định bằng các trường con mà không thiết lập rõ ràng bất kỳ trường con nào trên thông báo đó, bạn phải thêm từng trường con đối tượng có thể thay đổi vào FieldMask theo cách thủ công, tương tự như ví dụ trước đó tạo mặt nạ trường từ đầu.

Một ví dụ phổ biến là cập nhật chiến lược đặt giá thầu của chiến dịch mà không đặt bất kỳ trường nào trên chiến lược đặt giá thầu mới. Ví dụ sau đây minh hoạ cách cập nhật một chiến dịch để sử dụng chiến lược đặt giá thầu MaximizeConversions mà không đặt bất kỳ trường phụ nào trên chiến lược đặt giá thầu.

Trong trường hợp này, việc sử dụng các phương thức all_set_fields_of() và field_mask() của tiện ích FieldMasks không đạt được mục tiêu dự kiến.

Ví dụ sau đây tạo ra một mặt nạ trường bao gồm maximize_conversions. Tuy nhiên, Google Ads API không cho phép hành vi này để ngăn việc vô tình xoá các trường và tạo ra lỗi FieldMaskError.FIELD_HAS_SUBFIELDS.

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

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

# Sends the operation in a mutate request that results 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],
});

Ví dụ sau đây minh hoạ cách cập nhật đúng cách một chiến dịch để sử dụng chiến lược đặt giá thầu MaximizeConversions mà không đặt bất kỳ trường phụ nào của chiến lược đó.

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

# Creates a field mask from the existing campaign and adds the mutable subfield
# on the MaximizeConversions bidding strategy to the field mask. Because this
# field is included in the field mask but excluded from the campaign object,
# the Google Ads API sets 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.
#
# See the guide on assigning standard and portfolio bidding strategies
# (/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::V25::Services::CampaignService::CampaignOperation
  ->new({
    update     => $campaign,
    updateMask => $field_mask,
  });

Xoá các trường

Bạn có thể xoá các trường một cách rõ ràng bằng cách thêm các trường đó vào mặt nạ trường như trong ví dụ trước, hoặc bằng cách đặt trường thành một giá trị trống hoặc không xác định. Ví dụ: giả sử bạn có một chiến dịch sử dụng chiến lược đặt giá thầu MaximizeConversions và trường target_cpa_micros được đặt thành một giá trị lớn hơn 0.

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

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

Xin lưu ý rằng bạn chỉ có thể xoá các trường có trường con lồng nhau bằng cách xoá từng trường con riêng lẻ, như minh hoạ trong phần Trường đối tượng có trường con được xác định.