Aktualisierungen mit Feldmasken

In der Google Ads API erfolgen Aktualisierungen mithilfe einer Feldmaske. Die Feldmaske listet alle Felder auf, 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.

FieldMaskUtil

Die empfohlene Methode zum Generieren von Feldmasken ist die Verwendung unseres integrierten Dienstprogramms für Feldmasken, mit dem viele Details ausgeblendet werden. Außerdem können Sie Feldmasken automatisch generieren lassen, indem Sie die Änderungen an den Feldern der Entität überwachen.

So generieren Sie eine Feldmaske zum Aktualisieren einer Kampagne:

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

Mit dem Code wird zuerst ein leeres Campaign-Objekt erstellt. Anschließend wird der Ressourcenname festgelegt, um die API über die zu aktualisierende Kampagne zu informieren.

In diesem Beispiel wird die Methode client.field_mask.with für die Kampagne verwendet, um den Block zu starten, der die Aktualisierungen umfasst. Am Ende dieses Blocks vergleicht das Dienstprogramm den aktuellen Status der Kampagne nach dem Block mit dem Anfangsstatus der Kampagne vor dem Block und erstellt automatisch eine Feldmaske, in der die geänderten Felder aufgeführt sind. Sie können diese Feldmaske für den Vorgang wie folgt für den mutate-Aufruf erstellen:

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

Diese Methode wird empfohlen, wenn Sie einen komplizierten Vorgang ausführen und jeden Schritt genau steuern möchten. In den meisten Fällen können Sie jedoch das einfachere Ruby-Bibliotheksprogramm verwenden:

operation = client.operation.update_resource.campaign do |c|
  c.status = :PAUSED
  c.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

Mit dieser Methode wird automatisch eine neue leere Kampagnenressource erstellt, die Feldmaske anhand der Änderungen, die Sie im Block vornehmen, erstellt den Aktualisierungsvorgang und gibt den letzten Vorgang zurück, bei dem update und update_mask bereits ausgefüllt sind. Sie können eine Kampagne auch an die Methode campaign übergeben, um auch den Startstatus der Kampagne anzugeben. Dieses Muster funktioniert für alle Ressourcen, die den Aktualisierungsvorgang unterstützen.

Maske manuell erstellen

Wenn Sie eine neue Feldmaske ohne Verwendung von Dienstprogrammen für die Bibliothek erstellen möchten, müssen Sie zuerst ein Google::Protobuf::FieldMask erstellen, dann ein Array mit den Namen aller Felder erstellen, die Sie ändern möchten, und schließlich das Array dem Feld path der Feldmaske zuweisen.

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

Nachrichtenfelder und ihre Unterfelder aktualisieren

MESSAGE-Felder können Unterfelder haben (z. B. MaximizeConversions mit drei Feldern: target_cpa_micros, cpc_bid_ceiling_micros und cpc_bid_floor_micros) oder gar keines haben (z. B. ManualCpm).

Nachrichtenfelder ohne definierte Unterfelder

Wenn Sie ein MESSAGE-Feld aktualisieren, das keine Unterfelder definiert hat, verwenden Sie „FieldMaskUtil“, um eine Feldmaske zu generieren (siehe oben).

Nachrichtenfelder mit definierten untergeordneten Feldern

Wenn Sie ein MESSAGE-Feld aktualisieren, das mit Unterfeldern definiert ist, ohne eines der Unterfelder für diese Nachricht explizit festzulegen, müssen Sie jedes änderbare MESSAGE-Unterfeld manuell zu FieldMask hinzufügen, ähnlich wie im vorherigen Beispiel, in dem eine neue Feldmaske erstellt wurde.

Ein gängiges Beispiel ist das Aktualisieren der Gebotsstrategie einer Kampagne, ohne eines der Felder für die neue Gebotsstrategie festzulegen. Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne für die Verwendung der Gebotsstrategie MaximizeConversions aktualisieren, ohne eines der untergeordneten Felder der Gebotsstrategie festzulegen.

In diesem Beispiel wird durch die Verwendung des integrierten Vergleichs von FieldMaskUtil das beabsichtigte Ziel nicht erreicht.

Der folgende Code generiert eine Feldmaske, die maximize_conversions enthält. Die Google Ads API lässt dieses Verhalten jedoch nicht zu, um zu verhindern, dass Felder versehentlich gelöscht werden und der Fehler FieldMaskError.FIELD_HAS_SUBFIELDS ausgegeben wird.

Warnung: Der folgende Code führt zu einem Fehler.

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
# be included in a field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

Der folgende Code zeigt, wie eine Kampagne ordnungsgemäß für die Verwendung der Gebotsstrategie MaximizeConversions aktualisiert wird, ohne eines ihrer Unterfelder festzulegen.

Erfolgreich :Die Gebotsstrategie für die Kampagne wurde mit dem folgenden Code aktualisiert.

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

Felder löschen

Einige Felder können explizit gelöscht werden. Ähnlich wie im vorherigen Beispiel müssen Sie diese Felder explizit der Feldmaske hinzufügen. Angenommen, Sie haben eine Kampagne, in der die Gebotsstrategie MaximizeConversions verwendet wird, und für das Feld target_cpa_micros ist ein Wert größer als 0 festgelegt.

Der folgende Code wird ausgeführt. Allerdings wird maximize_conversions.target_cpa_micros der Feldmaske nicht hinzugefügt, sodass keine Änderungen am Feld target_cpa_micros vorgenommen werden:

Warnung: Dieser Code führt zu einem Fehler.

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

Der folgende Code zeigt, wie das Feld target_cpa_micros in der Gebotsstrategie MaximizeConversions richtig gelöscht wird.

Erfolgreich: Mit dem folgenden Code wird die target_cpa_micros gelöscht.

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

Bei Feldern, die in der Google Ads API protocol buffers als optional definiert sind, funktioniert der falsche Code wie vorgesehen. Da das target_cpa_micros-Feld jedoch kein optional-Feld ist, führt der „falsche“ Code nicht dazu, die Gebotsstrategie zu aktualisieren, um das Feld target_cpa zu löschen.

Wichtiger Hinweis :Wenn Sie ein Feld löschen möchten, ist es am sichersten, dieses Feld explizit der Feldmaske hinzuzufügen.