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 dem integrierten Dienstprogramm zu generieren. Dabei werden viele Details ausgeblendet und Sie können Feldmasken automatisch generieren, 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
Der Code erstellt zuerst ein leeres Kampagnenobjekt und legt dann den Ressourcennamen fest, um die API über die aktualisierte 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 Dienstprogramm den aktuellen Status der Kampagne nach dem Block mit dem ursprünglichen Status der Kampagne vor dem Block und erstellt automatisch eine Feldmaske, in der die geänderten Felder aufgelistet sind. Sie können diese Feldmaske der Operation beim Erstellen für den Mutate-Aufruf so zur Verfügung stellen:
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-Bibliotheksdienstprogramm 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 im Block erstellt, der Aktualisierungsvorgang erstellt und der endgültige Vorgang mit bereits ausgefüllten update- und update_mask-Werten zurückgegeben. Sie können der campaign-Methode auch eine Kampagne ü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 erstellen möchten, ohne Bibliotheks-Dienstprogramme zu verwenden, erstellen Sie zuerst eine Google::Protobuf::FieldMask, dann ein Array mit den Namen aller Felder, die Sie ändern möchten, und weisen Sie das Array schließlich dem path-Feld der Feldmaske zu.
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 keine (z. B. ManualCpm).
Nachrichtenfelder ohne definierte untergeordnete Felder
Wenn Sie ein MESSAGE-Feld aktualisieren, das nicht mit Unterfeldern definiert ist, verwenden Sie FieldMaskUtil, um eine Feldmaske zu generieren, wie oben beschrieben.
Nachrichtenfelder 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 veränderbaren MESSAGE-Unterfelder manuell zur FieldMask hinzufügen, ähnlich wie im vorherigen Beispiel, in dem eine Feldmaske von Grund auf neu erstellt wurde.
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 dass Sie eines der untergeordneten Felder der Gebotsstrategie festlegen.
In diesem Beispiel wird mit dem integrierten Vergleich von FieldMaskUtil nicht das gewünschte Ziel erreicht.
Mit dem folgenden Code wird eine Feldmaske generiert, die maximize_conversions enthält.
Die Google Ads API erlaubt dieses Verhalten jedoch nicht, um das versehentliche Löschen von Feldern zu verhindern. Es wird stattdessen der Fehler FieldMaskError.FIELD_HAS_SUBFIELDS 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, um die Gebotsstrategie MaximizeConversions zu verwenden, ohne eines ihrer untergeordneten Felder 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 der Feldmaske explizit hinzufügen. Angenommen, Sie haben eine Kampagne mit der Gebotsstrategie MaximizeConversions und das Feld target_cpa_micros ist auf einen Wert festgelegt, der über 0 liegt.
Der folgende Code wird ausgeführt, 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 für Felder, die in der Google Ads API protocol buffers als optional definiert sind, wie vorgesehen. Da target_cpa_micros jedoch kein optional-Feld ist, wird die Gebotsstrategie durch den „falschen“ Code nicht aktualisiert, um das Feld target_cpa zu löschen.