В 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 в клиентских библиотеках, работающих на 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::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 .
# 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)
});
Обратите внимание, что поля с вложенными подполями можно очистить только путем очистки каждого из отдельных подполей, как показано в разделе «Поля объектов с определенными подполями» .