Полевые маски

В Google Ads API обновления выполняются с использованием маски поля. В маске поля перечислены все поля, которые вы собираетесь изменить при обновлении, а любые указанные поля, которых нет в маске поля, игнорируются, даже если они отправлены на сервер.

Утилита FieldMasks

Рекомендуемый способ создания масок полей — использование нашей встроенной утилиты маски полей ( FieldMasks ), которая позволяет создавать маски полей из измененного объекта, а не создавать их с нуля.

Вот пример обновления кампании:

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

my $campaign_operation =
  Google::Ads::GoogleAds::V16::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::V16::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 . Однако API Google Рекламы не допускает такого поведения во избежание случайной очистки полей и выдает ошибку FieldMaskError.FIELD_HAS_SUBFIELDS .

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V16::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::V16::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::V16::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V16::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::V16::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::V16::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V16::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::V16::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

Обратите внимание, что поля с вложенными подполями можно очистить только путем очистки каждого из отдельных подполей, как показано в разделе «Поля объектов с определенными подполями» .