Aktualisierungen mit Feldmasken

In der Google Ads API werden Aktualisierungen mit 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

Die empfohlene Methode zum Generieren von Feldmasken ist die Verwendung des integrierten Feldmasken-Tools. Damit werden bestimmte Details ausgeblendet und Sie können Feldmasken automatisch generieren lassen, indem Sie die Änderungen an den Feldern der Einheit beobachten.

Im folgenden Beispiel wird gezeigt, wie eine Feldmaske zum Aktualisieren einer Kampagne generiert wird:

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 Vorgang angeben, wenn Sie ihn für den Mutate-Aufruf erstellen:

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

Diese Methode empfiehlt sich, wenn Sie einen komplexen Vorgang erstellen und jeden Schritt genau steuern möchten. In den meisten Fällen können Sie jedoch den Ressourcennamen (oder eine vorhandene Ressourceninstanz) an die Factory-Methode der Ruby-Bibliothek übergeben:

campaign_resource_name = client.path.campaign(customer_id, campaign_id)

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

Wenn Sie einen Ressourcennamen angeben, wird mit dieser Methode automatisch eine neue Kampagnenressource mit dem Wert resource_name erstellt. Außerdem wird die Feldmaske auf Grundlage der Änderungen, die Sie im Block vornehmen, erstellt, der Aktualisierungsvorgang wird erstellt und der endgültige Vorgang mit den Werten update und update_mask wird zurückgegeben. Sie können auch eine vorhandene Campaign-Proto-Instanz anstelle eines Ressourcennamenstrings übergeben, um den Startstatus der Kampagne anzugeben. Dieses Muster funktioniert für alle Ressourcen, die den Aktualisierungsvorgang unterstützen.

Feldmaske manuell erstellen

Wenn Sie eine Feldmaske von Grund auf neu erstellen möchten, ohne Bibliotheksdienstprogramme zu verwenden, erstellen Sie ein Google::Protobuf::FieldMask, erstellen Sie ein Array mit den Namen aller Felder, die Sie ändern möchten, und weisen Sie das Array dem Feld paths der Feldmaske zu:

mask = Google::Protobuf::FieldMask.new
mask.paths = ['status', 'name']

Nachrichtenfelder und ihre Unterfelder 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 gar keine (z. B. ManualCpm).

Nachrichtenfelder 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.

Nachrichtenfelder mit definierten Unterfeldern

Wenn Sie ein MESSAGE-Feld aktualisieren, das mit Unterfeldern definiert ist, ohne eines der Unterfelder in der Nachricht explizit festzulegen, müssen Sie jedes der änderbaren MESSAGE-Unterfelder manuell dem 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 die Aktualisierung der Gebotsstrategie einer Kampagne, ohne dass Felder für die neue Gebotsstrategie festgelegt werden. Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne aktualisieren, damit die Gebotsstrategie MaximizeConversions verwendet wird, ohne dass Sie Unterfelder für die Gebotsstrategie festlegen.

In diesem Beispiel wird das gewünschte 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 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 results 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]
)

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask starts empty. You can modify
# other fields in this block, except the message field intended to have a
# blank subfield.
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 größer als 0 festgelegt ist.

Wenn Sie in proto3 ein nicht optionales Skalarfeld auf seinen Standardwert (0) festlegen, ist das nicht davon zu unterscheiden, wenn Sie es in einer neuen Nachrichteninstanz nicht festlegen. Daher fügt FieldMaskUtil der Feldmaske maximize_conversions anstelle von maximize_conversions.target_cpa_micros hinzu, was zu einem FieldMaskError.FIELD_HAS_SUBFIELDS-Fehler führt.

# 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 includes 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it results 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 fails because the field mask is invalid.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation]
)

# Create a campaign including the maximize conversions fields right away, since
# they are manually added 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 can add a block here with
# other changes that are automatically 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 succeeds because the correct field mask is specified.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation]
)

Der automatische Vergleich funktioniert wie vorgesehen für Felder, die in den Protokollpuffern der Google Ads API als optional definiert sind. Da target_cpa_micros kein optional-Feld für MaximizeConversions ist, muss der Pfad explizit an update_mask.paths angehängt werden, um ihn zu löschen.