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.
FieldMaskUtil
Wir empfehlen, Feldmasken mit unserem integrierten Feldmasken-Tool zu generieren. Dadurch werden viele der spezifischen Details ausgeblendet und Sie können Feldmasken automatisch generieren lassen, indem Sie die Änderungen an den Feldern der Einheit beobachten.
So erstellen 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
Im Code wird zuerst ein leeres Campaign-Objekt erstellt und dann der zugehörige 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 mit den Aktualisierungen zu beginnen. Am Ende dieses Blocks vergleicht das Tool den aktuellen Status der Kampagne nach dem Block mit dem ursprünglichen Status der Kampagne vor dem Block und erstellt automatisch eine Feldmaske mit den geänderten Feldern. Sie können diese Feldmaske für den Mutate-Aufruf so für den Vorgang angeben:
operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask
Diese Methode empfiehlt sich, 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-Bibliotheks-Utility 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 wird auf Grundlage der Änderungen, die Sie im Block vornehmen, erstellt, der Aktualisierungsvorgang wird erstellt und der endgültige Vorgang wird zurückgegeben, wobei update und update_mask bereits ausgefüllt sind. Sie können auch eine Kampagne an die campaign-Methode übergeben, um den Startstatus der Kampagne anzugeben. Dieses Muster funktioniert für alle Ressourcen, die den Aktualisierungsvorgang unterstützen.
Maske manuell erstellen
Wenn Sie eine Feldmaske von Grund auf neu erstellen möchten, ohne Bibliotheksdienstprogramme zu verwenden, müssen Sie zuerst ein Google::Protobuf::FieldMask erstellen, dann ein Array mit den Namen aller Felder, 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 untergeordneten Felder aktualisieren
MESSAGE-Felder können Unterfelder haben (z. B. MaximizeConversions mit den drei Unterfeldern target_cpa_micros, cpc_bid_ceiling_micros und cpc_bid_floor_micros) oder auch keine (z. B. ManualCpm).
Nachrichtfelder ohne definierte Unterfelder
Wenn Sie ein MESSAGE-Feld aktualisieren, das nicht mit Unterfeldern definiert ist, verwenden Sie FieldMaskUtil, um eine Feldmaske zu generieren, wie oben beschrieben.
Nachrichtfelder mit definierten untergeordneten Feldern
Wenn Sie ein MESSAGE-Feld aktualisieren, das mit Unterfeldern definiert ist, ohne eines der Unterfelder in dieser Nachricht explizit festzulegen, müssen Sie jedes der änderbaren MESSAGE-Unterfelder manuell zur FieldMask hinzufügen. Das ist ähnlich wie im vorherigen Beispiel, in dem eine Feldmaske von Grund auf neu erstellt wurde.
Ein häufiges Beispiel ist das Aktualisieren der Gebotsstrategie einer Kampagne, ohne dass Felder der neuen Gebotsstrategie festgelegt werden. Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne so aktualisieren, dass die Gebotsstrategie MaximizeConversions verwendet wird, ohne dass Sie Unterfelder für die Gebotsstrategie festlegen.
In diesem Beispiel wird das beabsichtigte Ziel nicht erreicht, wenn der integrierte Vergleich von FieldMaskUtil verwendet wird.
Mit dem folgenden Code wird eine Feldmaske generiert, 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. Stattdessen wird ein FieldMaskError.FIELD_HAS_SUBFIELDS-Fehler ausgegeben.
# 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],
)
Im folgenden Code wird gezeigt, wie eine Kampagne richtig aktualisiert wird, damit die Gebotsstrategie MaximizeConversions verwendet wird, ohne dass die zugehörigen Unterfelder festgelegt werden.
# 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 ein Wert festgelegt ist, der größer als 0 ist.
Der folgende Code wird ausgeführt. Die maximize_conversions.target_cpa_micros wird jedoch nicht der Feldmaske hinzugefügt. Daher werden keine Änderungen am Feld target_cpa_micros vorgenommen:
# 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
Im folgenden Code wird gezeigt, 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
Der „falsche“ Code funktioniert wie vorgesehen für Felder, die in der Google Ads API protocol buffers als optional definiert sind. Da target_cpa_micros jedoch kein optional-Feld ist, wird die Gebotsstrategie durch den „falschen“ Code nicht aktualisiert, um das Feld target_cpa zu leeren.