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.

Feldmasken-Helper

Die empfohlene Methode zum Generieren von Feldmasken ist die Verwendung der Helper-Funktion field_mask, die im Paket google.api_core enthalten ist. Sie akzeptiert zwei Protobuf-Objekte und gibt ein Feldmaskenobjekt mit einer Liste paths zurück, die alle Felder enthält, die sich zwischen den beiden Objekten unterscheiden.

Wenn None als erster Parameter übergeben wird, enthält die Feldmaskenliste alle Felder des zweiten Protobuf-Objekts, die nicht auf ihren Standardwert festgelegt sind.

Nachdem das Feldmaskenobjekt erstellt wurde, sollte es in das Vorgangsobjekt kopiert werden, das an den Server gesendet wird.

Aktualisierung aus einem neuen lokalen Objekt

Im folgenden Beispiel erstellen Sie ein leeres CampaignOperation-Objekt und rufen ein leeres Campaign-Objekt aus dem Feld update ab. Anschließend ändern Sie dieses Kampagnenobjekt und erstellen eine neue Feldmaske, indem Sie es mit None vergleichen. Dadurch wird eine Feldmaske mit dem geänderten Feld network_settings.target_search_network generiert:

from google.ads.googleads.client import GoogleAdsClient
from google.api_core import protobuf_helpers

# Retrieve a GoogleAdsClient instance.
client = GoogleAdsClient.load_from_storage()

# Create a new campaign operation.
campaign_operation = client.get_type("CampaignOperation")

# Retrieve a new campaign object from its update field and set its resource
# name.
campaign = campaign_operation.update
campaign.resource_name = client.get_service("CampaignService").campaign_path(
    customer_id, campaign_id
)

# Mutate the campaign (use direct attribute assignment in proto-plus).
campaign.network_settings.target_search_network = False

# Create a field mask using the updated campaign.
# The field_mask helper is compatible with raw protobuf message instances,
# which you can access using the ._pb attribute.
field_mask = protobuf_helpers.field_mask(None, campaign._pb)

# Copy the field_mask onto the operation's update_mask field.
client.copy_from(campaign_operation.update_mask, field_mask)

Vorhandene Ressource aktualisieren

Im folgenden Beispiel wird eine vorhandene Kampagne aktualisiert, die aus der API abgerufen wurde. Dabei wird davon ausgegangen, dass eine gültige resource_name und customer_id vorhanden sind. Bei dieser Strategie enthält updated_campaign alle Felder, die für initial_campaign abgerufen wurden (einschließlich resource_name). Die generierte Feldmaske teilt der API mit, dass sich nur das Feld network_settings.target_search_network geändert hat:

from google.ads.googleads.client import GoogleAdsClient
from google.api_core import protobuf_helpers

# Retrieve a GoogleAdsClient instance.
client = GoogleAdsClient.load_from_storage()

# Retrieve an instance of the GoogleAdsService.
googleads_service = client.get_service("GoogleAdsService")

# Search query to retrieve the campaign. Quote string literals in GAQL.
query = f"""
    SELECT
      campaign.network_settings.target_search_network,
      campaign.resource_name
    FROM campaign
    WHERE campaign.resource_name = '{resource_name}'"""

# Submit a query to retrieve a campaign instance.
response = googleads_service.search_stream(
    customer_id=customer_id, query=query
)

# Iterate over results to retrieve the campaign.
initial_campaign = None
for batch in response:
    for row in batch.results:
        initial_campaign = row.campaign
        break

if not initial_campaign:
    raise ValueError(f"Campaign '{resource_name}' not found.")

# Create a new campaign operation.
campaign_operation = client.get_type("CampaignOperation")

# Set the copied campaign object to a variable for easy reference.
updated_campaign = campaign_operation.update

# Copy the retrieved campaign into the new campaign.
# client.copy_from works with both native protobuf messages and messages
# wrapped by the proto-plus library.
client.copy_from(updated_campaign, initial_campaign)

# Mutate the new campaign.
updated_campaign.network_settings.target_search_network = False

# Create a field mask by comparing initial and updated protobuf objects.
field_mask = protobuf_helpers.field_mask(
    initial_campaign._pb, updated_campaign._pb
)

# Copy the field mask onto the operation's update_mask field.
# Note that the client's copy_from method works with both native messages
# and messages wrapped by proto-plus, including google.protobuf.field_mask_pb2.
client.copy_from(campaign_operation.update_mask, field_mask)

Felder löschen oder leere Nachrichten festlegen

Beim Vergleich mit None ignoriert der Helper field_mask Felder, die auf leere oder Standardwerte festgelegt sind. Wenn Sie ein Feld explizit löschen oder ein leeres Nachrichtenfeld festlegen möchten, hängen Sie den Feldpfad direkt an campaign_operation.update_mask.paths an. Weitere Informationen finden Sie unter Leere Nachrichtenobjekte als Felder festlegen.