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

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

утилита 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),
  });

В этом примере сначала создается объект Campaign путем указания его имени ресурса с помощью утилиты ResourceNames , чтобы API знал, какая кампания обновляется.

В примере используется метод FieldMasks::all_set_fields_of() объекта Campaign для автоматического создания маски поля, которая перечисляет все установленные поля. Затем вы можете передать возвращенную маску непосредственно в вызов функции обновления.

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

Обновить поля объекта и их подполя.

Поля объекта могут иметь подполя (например, MaximizeConversions , которое включает в себя подполя, такие как target_cpa_micros ), или не иметь их вовсе (например, ManualCpm ).

Поля объекта, для которых не определены подполя

В Perl поле объекта эквивалентно сообщению MESSAGE в protobuf в клиентских библиотеках, работающих на gRPC. При обновлении поля объекта, которое не определено с какими-либо подполями, используйте утилиту FieldMasks для генерации маски поля, как описано в предыдущем разделе.

Поля объекта с определенными подполями

При обновлении поля объекта, определенного с подполями, без явного указания каких-либо из этих подполей в сообщении, необходимо вручную добавить каждое из изменяемых подполей объекта в FieldMask , аналогично предыдущему примеру, в котором маска поля создается с нуля.

Один из распространенных примеров — обновление стратегии назначения ставок для кампании без указания каких-либо полей в новой стратегии. Следующий пример демонстрирует, как обновить кампанию, чтобы использовать стратегию назначения ставок MaximizeConversions без указания каких-либо подполей в стратегии назначения ставок.

В данном случае использование методов all_set_fields_of() и field_mask() утилиты FieldMasks не позволяет достичь желаемого результата.

В следующем примере генерируется маска поля, включающая maximize_conversions . Однако API Google Ads не позволяет использовать такое поведение для предотвращения случайной очистки полей и выдает ошибку 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),
  });

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