Maski terenowe

W interfejsie Google Ads API aktualizacje są wprowadzane przy użyciu maski pola. Maska pola zawiera wszystkie pola, które chcesz zmienić w ramach aktualizacji. Wszystkie określone pola, których nie ma w masce pola, są ignorowane, nawet jeśli zostaną wysłane na serwer.

Użyteczność masek pól

Zalecanym sposobem generowania masek pól jest użycie naszej wbudowanej funkcji maski pól (FieldMasks), która pozwala generować maski pól ze zmodyfikowanego obiektu, zamiast tworzyć je od zera.

Oto przykład aktualizacji kampanii:

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

W tym przykładzie najpierw tworzysz obiekt Campaign, ustawiając za pomocą narzędzia ResourceNames nazwę jego zasobu, aby interfejs API wiedział, która kampania jest aktualizowana.

W przykładzie użyto w kampanii metody FieldMasks::all_set_fields_of(), aby automatycznie utworzyć maskę pola, która zawiera wszystkie ustawione pola. Zwróconą maskę możesz następnie przekazać bezpośrednio do wywołania aktualizacji.

FieldMasks::all_set_fields_of() to wygodna metoda korzystania z FieldMasks::field_mask(). Porównuje on przekazany obiekt z pustym obiektem tej samej klasy. W powyższym kodzie można też użyć polecenia

field_mask(Google::Ads::GoogleAds::V16::Resources::Campaign->new({}), $campaign)

zamiast all_set_fields_of($campaign).

Ręczne tworzenie maski

Aby utworzyć maskę pola od zera, najpierw utwórz obiekt Google::Ads::GoogleAds::Common::FieldMask, następnie odwołanie do tablicy zawierające nazwy wszystkich pól, które chcesz zmienić, i przypisz odwołanie do tablicy do pola paths maski pola.

my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
    paths => ["status", "name"]
  });

Aktualizowanie pól obiektów i ich pól podrzędnych

Pola obiektu mogą zawierać pola podrzędne (np. MaximizeConversions, które mają 3 pola: target_cpa_micros, cpc_bid_ceiling_micros i cpc_bid_floor_micros) albo mogą nie mieć żadnych pól podrzędnych (np. ManualCpm).

Pola obiektu bez zdefiniowanych pól podrzędnych

Pole obiektu w języku Perl jest odpowiednikiem protokołu MESSAGE w bibliotekach klienta działających w gRPC. Gdy aktualizujesz pole obiektu, które nie jest zdefiniowane za pomocą żadnych pól podrzędnych, użyj narzędzia FieldMasks w celu wygenerowania maski pola w sposób opisany powyżej.

Pola obiektów ze zdefiniowanymi polami podrzędnymi

Aktualizując pole obiektu, które jest zdefiniowane z polami podrzędnymi, bez ustawiania konkretnych pól podrzędnych w wiadomości, musisz ręcznie dodać do pola FieldMask wszystkie zmienne pola podrzędne obiektu, podobnie jak w przykładzie powyżej, który tworzy maskę pola od podstaw.

Typowym przykładem jest aktualizacja strategii ustalania stawek w kampanii bez ustawiania jakichkolwiek pól w nowej strategii. Z przykładu poniżej dowiesz się, jak zaktualizować kampanię, aby korzystała ze strategii ustalania stawek MaximizeConversions bez ustawiania żadnych pól podrzędnych tej strategii.

W tym przypadku użycie metod all_set_fields_of() i field_mask() narzędzia FieldMasks nie pozwala osiągnąć zamierzonego celu.

Poniższy przykład pokazuje maskę pola zawierającą maximize_conversions. Interfejs Google Ads API nie zezwala jednak na takie działanie, aby zapobiec przypadkowemu wyczyszczeniu pól i wystąpi błąd 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]
  });

Z przykładu poniżej dowiesz się, jak prawidłowo zaktualizować kampanię, aby korzystała ze strategii ustalania stawek MaximizeConversions bez ustawiania jej pól podrzędnych.

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

Czyszczenie pól

Pola można czyścić bezpośrednio, dodając je do maski pola w sposób opisany powyżej lub ustawiając je na puste lub niezdefiniowane wartości. Załóżmy na przykład, że masz kampanię, która korzysta ze strategii ustalania stawek MaximizeConversions, a pole target_cpa_micros zawiera wartość większą niż 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)
  });

Pamiętaj, że pola z zagnieżdżonymi polami podrzędnymi można wyczyścić tylko przez wyczyszczenie każdego z nich, jak pokazano w sekcji Pola obiektu ze zdefiniowanymi polami podrzędnymi.