Maski terenowe

W interfejsie Google Ads API aktualizacje są przeprowadzane za pomocą maski pola. Maska pola zawiera listę wszystkie pola, które chcesz zmienić w ramach aktualizacji, oraz wszystkie określone pola, nieuwzględnione w masce pola są ignorowane, nawet jeśli zostały wysłane na serwer.

Narzędzie FieldMasks

Zalecanym sposobem generowania masek pól jest użycie naszej wbudowanej maski pola za usługi komunalne (FieldMasks), który pozwala generować maski pól na podstawie zmodyfikowanego obiektu, zamiast od zera.

Oto przykład aktualizowania kampanii:

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

W tym przykładzie najpierw tworzymy obiekt Campaign przez ustawienie jego nazwy zasobu za pomocą narzędzia ResourceNames. Dzięki temu interfejs API będzie wiedzieć, która kampania jest aktualizowana.

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

FieldMasks::all_set_fields_of() to wygodny sposób na FieldMasks::field_mask() Porównuje przesłany obiekt z pustym obiektem tej samej klasy. W przypadku powyżej, możesz też użyć

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

zamiast all_set_fields_of($campaign).

Ręczne tworzenie maski

Aby utworzyć od podstaw maskę pola, najpierw Google::Ads::GoogleAds::Common::FieldMask obiekt, a następnie ustaw odwołanie do tablicy wypełnione nazwami wszystkich pól którą chcesz zmienić, i na koniec przypisać odwołanie do tablicy do funkcji maski pola paths.

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 (takie jak MaximizeConversions, która obejmuje 3 elementy: target_cpa_micros, cpc_bid_ceiling_micros i cpc_bid_floor_micros); lub nie mogą nie mieć żadnej (np. ManualCpm).

Pola obiektu bez zdefiniowanych pól podrzędnych

Pole obiektu w języku Perl jest odpowiednikiem bufora protokołu MESSAGE w kliencie działających w gRPC. Podczas aktualizowania pola obiektu, które nie jest zdefiniowane z dowolnymi polami podrzędnymi, użyj narzędzia FieldMasks do wygenerowania maski pola, opisane powyżej.

Pola obiektu ze zdefiniowanymi polami podrzędnymi

Podczas aktualizowania pola obiektu zdefiniowanego za pomocą pól podrzędnych bez jawnie ustawiając dowolne z pól podrzędnych tej wiadomości, musisz ręcznie dodać każde zmiennych pól podrzędnych obiektów FieldMask, podobnie jak w przykładzie powyżej. który tworzy od zera maskę pola.

Typowy przykład to aktualizacja strategii ustalania stawek w kampanii bez ustawiania w nowej strategii określania stawek. Poniższy przykład pokazuje, jak zaktualizować kampanię, tak aby korzystała z Strategia ustalania stawek: MaximizeConversions bez konfigurowania żadnych pól podrzędnych strategii ustalania stawek.

W tym przypadku za pomocą metod all_set_fields_of() i field_mask() funkcji Narzędzie FieldMasks nie osiąga zamierzonego celu.

Ten przykład generuje maskę pola zawierającą maximize_conversions Interfejs Google Ads API nie zezwala na to jednak. w celu uniknięcia przypadkowego wyczyszczenia pól i wygenerowania FieldMaskError.FIELD_HAS_SUBFIELDS .

Ostrzeżenie: poniższy kod powoduje błąd.

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

Poniższy przykład pokazuje, jak prawidłowo zaktualizować kampanię, aby korzystała z MaximizeConversions strategia ustalania stawek bez ustawienia żadnego z pól podrzędnych.

Sukces: poniższy kod zaktualizował strategię ustalania stawek w kampanii.

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

Czyszczenie pól

Pola można wyczyścić jawnie, dodając je do maski pola, jak pokazano na obrazku powyżej lub przez ustawienie w polu wartości pustej bądź niezdefiniowanej. Przykład: zakładamy, że masz kampanię, która korzysta ze strategii ustalania stawek MaximizeConversions a w polu target_cpa_micros ustawiona jest wartość większa niż 0

Sukces: poniższy kod czyści pole 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)
  });

Pamiętaj, że pola z zagnieżdżonymi polami podrzędnymi można wyczyścić tylko przez usunięcie każdego z poszczególnych pól podrzędnych, co pokazuje pola obiektów ze zdefiniowanymi wartościami .