필드 마스크

Google Ads API에서는 필드 마스크를 사용하여 업데이트가 이루어집니다. 필드 마스크에는 업데이트로 변경하려는 모든 필드가 나열되며, 지정된 필드 중 필드 마스크에 없는 필드는 서버로 전송되더라도 무시됩니다.

FieldMasks 유틸리티

필드 마스크를 생성하는 데는 수정된 객체에서 필드 마스크를 생성하여 처음부터 빌드하지 않아도 되는 내장 필드 마스크 유틸리티 (FieldMasks)를 사용하는 것이 좋습니다.

다음은 캠페인을 업데이트하는 예입니다.

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

이 예에서는 먼저 ResourceNames 유틸리티를 사용하여 리소스 이름을 설정하여 Campaign 객체를 만듭니다. 이렇게 하면 API에서 업데이트되는 캠페인을 알 수 있습니다.

이 예에서는 캠페인에서 FieldMasks::all_set_fields_of() 메서드를 사용하여 설정된 모든 필드를 열거하는 필드 마스크를 자동으로 생성합니다. 그런 다음 반환된 마스크를 업데이트 호출에 직접 전달할 수 있습니다.

FieldMasks::all_set_fields_of()은 FieldMasks::field_mask()의 편의 메서드입니다. 전달된 객체를 동일한 클래스의 빈 객체와 비교합니다. 위 코드에서 다음을 사용할 수도 있습니다.

field_mask(
  Google::Ads::GoogleAds::V25::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"],
});

객체 필드 및 하위 필드 업데이트

객체 필드에는 하위 필드 (예: target_cpa_micros과 같은 하위 필드가 포함된 MaximizeConversions)가 있을 수도 있고 전혀 없을 수도 있습니다 (예: ManualCpm).

정의된 하위 필드가 없는 객체 필드

Perl의 객체 필드는 gRPC에서 실행되는 클라이언트 라이브러리의 protobuf MESSAGE와 동일합니다. 하위 필드로 정의되지 않은 객체 필드를 업데이트할 때는 이전 섹션에 설명된 대로 FieldMasks 유틸리티를 사용하여 필드 마스크를 생성합니다.

하위 필드가 정의된 객체 필드

메시지에서 하위 필드를 명시적으로 설정하지 않고 하위 필드로 정의된 객체 필드를 업데이트할 때는 처음부터 필드 마스크를 만드는 이전 예와 마찬가지로 FieldMask에 변경 가능한 객체 하위 필드를 각각 수동으로 추가해야 합니다.

일반적인 예로 새 입찰 전략에서 필드를 설정하지 않고 캠페인의 입찰 전략을 업데이트하는 경우가 있습니다. 다음 예에서는 입찰 전략의 하위 필드를 설정하지 않고 MaximizeConversions 입찰 전략을 사용하도록 캠페인을 업데이트하는 방법을 보여줍니다.

이 경우 FieldMasks 유틸리티의 all_set_fields_of() 및 field_mask() 메서드를 사용해도 의도한 목표를 달성할 수 없습니다.

다음 예시에서는 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::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],
});

다음 예에서는 하위 필드를 설정하지 않고 MaximizeConversions 입찰 전략을 사용하도록 캠페인을 올바르게 업데이트하는 방법을 보여줍니다.

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

필드 지우기

필드는 앞의 예와 같이 필드 마스크에 추가하거나 필드를 빈 값 또는 정의되지 않은 값으로 설정하여 명시적으로 삭제할 수 있습니다. 예를 들어 MaximizeConversions 입찰 전략을 사용하는 캠페인이 있고 target_cpa_micros 필드가 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),
  });

중첩된 하위 필드가 있는 필드는 정의된 하위 필드가 있는 객체 필드에 설명된 대로 각 개별 하위 필드를 삭제해야만 삭제할 수 있습니다.