필드 마스크

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와 동일합니다. 라이브러리를 제공합니다 정의되지 않은 객체 필드를 업데이트할 때 하위 필드와 함께 사용하려면 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)
  });

중첩된 하위 필드가 있는 필드는 각 필드를 지워야 지울 수 있습니다. 정의된 객체 필드 하위 필드를 참고하세요.