Feldmasken

In der Google Ads API werden Aktualisierungen mithilfe einer Feldmaske vorgenommen. In der Feldmaske sind alle Felder aufgeführt, die Sie mit der Aktualisierung ändern möchten. Alle angegebenen Felder, die nicht in der Feldmaske enthalten sind, werden ignoriert, auch wenn sie an den Server gesendet werden.

Dienstprogramm für FieldMasks

Wir empfehlen, Feldmasken mit dem integrierten Dienstprogramm für Feldmasken (FieldMasks) zu generieren. Damit können Sie Feldmasken aus einem geänderten Objekt generieren, anstatt sie von Grund auf neu zu erstellen.

Hier ein Beispiel für die Aktualisierung einer Kampagne:

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

my $campaign_operation =
  Google::Ads::GoogleAds::V19::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

In diesem Beispiel wird zuerst ein Campaign-Objekt erstellt, indem der Ressourcenname mit dem Dienstprogramm ResourceNames festgelegt wird. So weiß die API, welche Kampagne aktualisiert wird.

Im Beispiel wird die Methode FieldMasks::all_set_fields_of() für die Kampagne verwendet, um automatisch eine Feldmaske zu erstellen, die alle festgelegten Felder auflistet. Sie können die zurückgegebene Maske dann direkt an den Updateaufruf übergeben.

FieldMasks::all_set_fields_of() ist eine praktische Methode für FieldMasks::field_mask(). Dabei wird das übergebene Objekt mit einem leeren Objekt derselben Klasse verglichen. Im Code oben könntest du also auch

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

anstelle von all_set_fields_of($campaign).

Maske manuell erstellen

Wenn Sie eine Feldmaske von Grund auf erstellen möchten, erstellen Sie zuerst ein Google::Ads::GoogleAds::Common::FieldMask-Objekt, erstellen Sie dann eine Arrayreferenz mit den Namen aller Felder, die Sie ändern möchten, und weisen Sie die Arrayreferenz schließlich dem Feld paths der Feldmaske zu.

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

Objektfelder und ihre untergeordneten Felder aktualisieren

Objektfelder können untergeordnete Felder haben (z. B. MaximizeConversions mit den drei untergeordneten Feldern target_cpa_micros, cpc_bid_ceiling_micros und cpc_bid_floor_micros) oder keine (z. B. ManualCpm).

Objektfelder ohne definierte untergeordnete Felder

Ein Objektfeld in Perl entspricht einem Protobuf-MESSAGE in Clientbibliotheken, die auf gRPC ausgeführt werden. Wenn Sie ein Objektfeld aktualisieren, das nicht mit Unterfeldern definiert ist, generieren Sie mit dem Dienstprogramm „FieldMasks“ eine Feldmaske, wie oben beschrieben.

Objektfelder mit definierten Unterfeldern

Wenn Sie ein Objektfeld aktualisieren, das mit untergeordneten Feldern definiert ist, ohne eines der untergeordneten Felder für diese Nachricht explizit festzulegen, müssen Sie jedes der veränderbaren Objektunterfelder manuell zur FieldMask hinzufügen. Ähnlich wie im Beispiel oben, in dem eine Feldmaske von Grund auf neu erstellt wird.

Ein häufiges Beispiel ist die Aktualisierung der Gebotsstrategie einer Kampagne, ohne dass die Felder der neuen Gebotsstrategie festgelegt werden. Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne so aktualisieren, dass die Gebotsstrategie MaximizeConversions verwendet wird, ohne eines der Unterfelder für die Gebotsstrategie festzulegen.

In diesem Fall wird das gewünschte Ziel nicht mit den Methoden all_set_fields_of() und field_mask() des Dienstprogramms „FieldMasks“ erreicht.

Im folgenden Beispiel wird eine Feldmaske mit maximize_conversions generiert. Die Google Ads API erlaubt dieses Verhalten jedoch nicht, um das versehentliche Löschen von Feldern zu verhindern. Stattdessen wird der Fehler FieldMaskError.FIELD_HAS_SUBFIELDS ausgegeben.

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

Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne so aktualisieren, dass die Gebotsstrategie MaximizeConversions verwendet wird, ohne eines ihrer untergeordneten Felder festzulegen.

# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V19::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V19::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::V19::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => $field_mask
  });

Felder löschen

Felder können explizit gelöscht werden, indem Sie sie wie oben gezeigt der Feldmaske hinzufügen oder das Feld auf einen leeren oder nicht definierten Wert festlegen. Angenommen, Sie haben eine Kampagne mit der Gebotsstrategie MaximizeConversions und das Feld target_cpa_micros ist auf einen Wert festgelegt, der über 0 liegt.

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

Felder mit verschachtelten Unterfeldern können nur gelöscht werden, indem alle einzelnen Unterfelder gelöscht werden, wie unter Objektfelder mit definierten Unterfeldern gezeigt.