Aktualisierungen mit Feldmasken

In der Google Ads API werden Aktualisierungen mithilfe einer Feldmaske vorgenommen. In der Feldmaske sind alle Felder aufgeführt, die Sie mit dem Update ä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-Dienstprogramms. Es blendet bestimmte Details aus und ermöglicht es Ihnen, Feldmasken automatisch zu generieren, indem die Änderungen an den Feldern der Entität überwacht werden.

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

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 Campaign-Objekt und legt dann den Ressourcennamen fest, 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 starten. 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 aufgeführt sind. Sie können diese Feldmaske für den Vorgang angeben, wenn Sie sie für den Mutate-Aufruf so erstellen:

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

Diese Methode wird empfohlen, 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 Ressourcennamenstring angeben, wird mit dieser Methode automatisch eine neue Kampagnenressource mit ausgefülltem resource_name erstellt. Die Feldmaske wird basierend auf den Änderungen erstellt, die Sie im Block vornehmen. Außerdem wird der Aktualisierungsvorgang erstellt und der endgültige Vorgang mit bereits ausgefülltem update und update_mask zurückgegeben. Sie können auch eine vorhandene Campaign-Proto-Instanz anstelle eines Ressourcennamen-Strings ü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 ohne Bibliotheksdienstprogramme erstellen möchten, erstellen Sie ein Google::Protobuf::FieldMask, füllen 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, das drei Unterfelder hat: 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 dieser Nachricht explizit festzulegen, müssen Sie jedes der änderbaren MESSAGE-Unterfelder manuell zur FieldMask hinzufügen, ähnlich wie im vorherigen Beispiel, in dem eine Feldmaske von Grund auf neu erstellt wurde.

Ein gängiges 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 so aktualisieren, dass die Gebotsstrategie MaximizeConversions verwendet wird, ohne dass Unterfelder der Gebotsstrategie festgelegt werden.

In diesem Beispiel wird mit dem integrierten Vergleich von FieldMaskUtil nicht das beabsichtigte Ziel erreicht.

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. Es 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 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 zur Feldmaske hinzufügen. Angenommen, Sie haben eine Kampagne, die die Gebotsstrategie MaximizeConversions verwendet, und das Feld target_cpa_micros ist auf einen Wert größer als 0 festgelegt.

In proto3 ist das Festlegen eines nicht optionalen Skalarfelds auf den Standardwert (0) nicht davon zu unterscheiden, ob es in einer neuen Nachrichteninstanz nicht festgelegt ist. 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 Protokollzwischenspeichern der Google Ads API als optional definiert sind. Da target_cpa_micros kein optional-Feld in MaximizeConversions ist, muss der Pfad zu update_mask.paths explizit angehängt werden, um ihn zu löschen.