Aktualisierungen mit Feldmasken

In der Google Ads API werden Aktualisierungen mit einer Feldmaske vorgenommen. Die Feldmaske enthält alle Felder, 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.

Assistent für Feldmasken

Die empfohlene Methode zum Generieren von Feldmasken ist die Verwendung der Hilfsfunktion field_mask, die im Paket google.api_core enthalten ist. Die Funktion akzeptiert zwei Protobuf-Objekte und gibt ein Feldmaskenobjekt mit einer paths-Liste 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.

Mit einem neuen lokalen Objekt aktualisieren

Im folgenden Beispiel wird ein leeres CampaignOperation-Objekt erstellt und ein leeres Campaign-Objekt aus dem Feld update abgerufen. Sie ändern dann 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 über die API abgerufen wurde. Dabei wird von einem gültigen resource_name und customer_id ausgegangen. Bei dieser Strategie werden alle Felder, die für initial_campaign abgerufen wurden (einschließlich der resource_name), von updated_campaign freigegeben. 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 werden Felder, die auf leere oder Standardwerte gesetzt sind, vom field_mask-Helfer ignoriert. Wenn Sie ein Feld explizit leeren 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.