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 Dienstprogramms für Feldmasken. Dadurch werden bestimmte Details ausgeblendet und Sie können Feldmasken automatisch generieren, indem Sie die Änderungen an den Feldern der Entität beobachten.

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 zu starten, der die Aktualisierungen umfasst. 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 mit den geänderten Feldern. Sie können diese Feldmaske für den Vorgang bereitstellen, wenn Sie sie für den Mutate-Aufruf erstellen. Das sieht so aus:

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 eine Ressourcennamen-String angegeben wird, erstellt diese Methode automatisch eine neue Kampagnenressource mit resource_name ausgefüllt, erstellt die Feldmaske basierend auf den Änderungen, die Sie im Block vornehmen, erstellt den Aktualisierungsvorgang und gibt den endgültigen Vorgang mit update und update_mask bereits ausgefüllt zurück. Sie können auch eine vorhandene Campaign-Proto-Instanz anstelle einer Ressourcennamen-String ü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 Dienstprogramme der Bibliothek zu verwenden, erstellen Sie eine 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, für das keine Unterfelder definiert sind, verwenden Sie FieldMaskUtil, um eine Feldmaske zu generieren, wie bereits beschrieben.

Nachrichtenfelder mit definierten Unterfeldern

Wenn Sie ein MESSAGE-Feld aktualisieren, für das Unterfelder definiert sind, ohne eines der Unterfelder für diese 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 die Felder für die neue Gebotsstrategie festzulegen. Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne so aktualisieren, dass die MaximizeConversions Gebotsstrategie verwendet wird, ohne die Unterfelder für die Gebotsstrategie festzulegen.

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

Der folgende Code generiert eine Feldmaske, 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 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 es nicht möglich, zu unterscheiden, ob ein nicht optionales Skalarfeld auf den Standardwert (0) festgelegt oder in einer neuen Nachrichteninstanz nicht festgelegt wurde. 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 als optional in den Google Ads API Protokollpuffern 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 es zu löschen.