Aktualisierungen mit Feldmasken

In der Google Ads API werden Aktualisierungen mithilfe einer Feldmaske vorgenommen. Die Feldmaske listet alle Felder, die Sie mit der Aktualisierung ändern möchten, sowie 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 unserer integrierten Feldmaske das viele spezifische Details verbirgt und es Ihnen ermöglicht, Felder automatisch maskiert. Dabei werden die Änderungen überwacht, die Sie an den Feldern der Entität vornehmen.

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 zu Beginn die Methode client.field_mask.with für die Kampagne verwendet. der die Updates umfasst. Am Ende dieses Blocks zeigt das Dienstprogramm den aktuellen Status der Kampagne nach der Blockierung mit dem ersten der Kampagne vor der Blockierung. Daraufhin wird automatisch ein Feld Maske mit der Auflistung der geänderten Felder. Sie können diese Feldmaske wenn sie für den mutate-Aufruf wie folgt erstellt werden:

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

Diese Methode wird empfohlen, wenn Sie eine komplizierte Operation Sie möchten jeden Schritt genau kontrollieren. In den meisten Fällen können Sie jedoch einfacheres Dienstprogramm der Ruby-Bibliothek:

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 basierend auf den Änderungen, die Sie im Block vornehmen, erstellt das Update und gibt den endgültigen Vorgang mit update und update_mask zurück. bereits ausgefüllt sind. Sie können eine Kampagne auch an die Methode campaign übergeben, Startstatus der Kampagne angeben. Dieses Muster funktioniert für alle die den Aktualisierungsvorgang unterstützen.

Maske manuell erstellen

Um eine neue Feldmaske ohne Verwendung von Bibliotheksdienstprogrammen zu erstellen, würde zuerst ein Google::Protobuf::FieldMask und dann ein Array erstellen mit den Namen aller Felder gefüllt, die Sie ändern möchten. Weisen Sie das Array dem Feld path der Feldmaske zu.

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

Nachrichtenfelder und ihre untergeordneten Felder aktualisieren

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

Nachrichtenfelder ohne definierte untergeordnete Felder

Wenn Sie ein MESSAGE-Feld aktualisieren, das nicht mit einem Unterfeld definiert ist, verwenden Sie die Methode FieldMaskUtil zum Generieren einer Feldmaske, wie zuvor dargestellt.

Nachrichtenfelder mit definierten untergeordneten Feldern

Beim Aktualisieren eines MESSAGE-Felds, das mit Unterfeldern ohne explizit eines der Unterfelder der Nachricht festlegen, müssen Sie jedes der änderbaren MESSAGE-Unterfelder den FieldMask entspricht, ähnlich dem Beispiel für ein vorheriges Beispiel, in dem eine komplett neue Feldmaske erstellt wurde.

Ein häufiges Beispiel ist die Aktualisierung der Gebotsstrategie einer Kampagne, ohne eines der Felder in der neuen Gebotsstrategie. Im folgenden Beispiel zeigt, wie Sie eine Kampagne aktualisieren, um Gebotsstrategie MaximizeConversions ohne Unterfelder der Gebotsstrategie festzulegen.

In diesem Beispiel ist die Verwendung des integrierten Vergleichs von FieldMaskUtil das beabsichtigte Ziel zu erreichen.

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

Warnung: Der folgende Code erzeugt einen 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 des MaximizeConversions-Gebotsstrategie, ohne eines ihrer untergeordneten Felder festzulegen.

Erfolgreich :Mit dem Code unten wurde die Gebotsstrategie für die Kampagne 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 werden der Feldmaske explizit hinzugefügt. Angenommen, Sie haben eine Kampagne mit der Gebotsstrategie „MaximizeConversions“ verwendet, Das Feld target_cpa_micros enthält einen Wert, der größer als 0 ist.

Der folgende Code wird ausgeführt: Der maximize_conversions.target_cpa_micros werden der Feldmaske nicht hinzugefügt und es werden keine Änderungen Feld target_cpa_micros:

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

Im folgenden Code wird gezeigt, wie das Feld target_cpa_micros in der Gebotsstrategie MaximizeConversions richtig gelöscht wird.

Erfolg: 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

Beachten Sie, dass das Feld wie vorgesehen funktioniert, wenn der Code als optional in der Google Ads API protocol buffers. Aber da die target_cpa_micros ist kein optional-Feld vorhanden ist, damit die Gebotsstrategie nicht aktualisiert wird um das Feld target_cpa zu löschen.

Wichtiger Hinweis :Wenn Sie ein Feld löschen möchten, ist es am sichersten, das Feld explizit zur Feldmaske hinzufügen.