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.
# 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.
# 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:
# 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.
# 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.