Khẩu trang tại chỗ

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

Tiện ích FieldMasks

Bạn nên dùng mặt nạ trường tích hợp sẵn theo cách đề xuất để tạo mặt nạ trường phần mềm tiện ích (FieldMasks), cho phép bạn tạo mặt nạ trường từ đối tượng đã sửa đổi thay vì tạo mặt nạ từ đầu.

Dưới đây là ví dụ về cách cập nhật chiến dịch:

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)
  });

Trước tiên, ví dụ này sẽ tạo một đối tượng Campaign bằng cách đặt tên tài nguyên bằng cách sử dụ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 pháp FieldMasks::all_set_fields_of() cho chiến dịch để tự động tạo một mặt nạ trường liệt kê tất cả đặt các trường. Sau đó, bạn có thể truyền trực tiếp mặt nạ được trả về đến lệnh gọi cập nhật.

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

field_mask(Google::Ads::GoogleAds::V17::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 sẽ tạo một Google::Ads::GoogleAds::Common::FieldMask đối tượng, sau đó tạo một tham chiếu mảng được điền sẵn tên của tất cả các trường mà bạn dự định thay đổi và cuối cùng là gán tham chiếu mảng cho mặt nạ trường Trường paths.

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 phụ của các trường đó

Các trường đối tượng có thể có trường phụ (chẳng hạn như MaximizeConversions có 3 thuộc tính: target_cpa_micros, cpc_bid_ceiling_micros và cpc_bid_floor_micros); hoặc chúng có thể không có gì (chẳng hạn như ManualCpm).

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

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

Các trường đối tượng có trường phụ đã 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 phụ mà không có trường hợp rõ ràng cài đặt bất kỳ trường phụ nào trên thông báo đó, bạn phải thêm từng trường các trường phụ của đối tượng có thể biến đổi thành FieldMask, tương tự như ví dụ ở trên để 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 của các trường trên chiến lược đặt giá thầu mới. Ví dụ dưới đây minh hoạ cách hãy cập nhật chiến dịch để sử dụng MaximizeConversions chiến lược đặt giá thầu mà không cần thiết lập bất kỳ trường phụ nào trong chiến lược đặt giá thầu.

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

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

Cảnh báo: Mã sau đây tạo ra lỗi.

# 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]
  });

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

Thành công: Mã bên dưới đã cập nhật thành công chiến lược đặt giá thầu của chiến dịch.

# 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
  });

Xoá 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ư minh hoạ ở trên hoặc bằng cách đặt trường này thành 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 với giá trị lớn hơn 0.

Thành công: Mã sau đây sẽ xoá trường 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)
  });

Lưu ý rằng bạn chỉ có thể xoá các trường có trường phụ lồng nhau bằng cách xoá từng trường các trường phụ riêng lẻ, như được minh hoạ trong Các trường đối tượng với dữ liệu đã xác định trường phụ.