Feldmasken

In der Google Ads API werden Aktualisierungen mithilfe einer Feldmaske vorgenommen. Die Feldmaske (google.protobuf.FieldMask) enthält eine Liste von Feldpfaden in snake_case, 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.

FieldMasks-Dienstprogramm

Die empfohlene Methode zum Generieren von Feldmasken in der Java-Clientbibliothek ist die Verwendung der integrierten Dienstprogrammklasse FieldMasks. Damit können Sie Feldmasken aus einem geänderten Objekt generieren, anstatt sie von Grund auf neu zu erstellen.

Hier ein Beispiel für die Aktualisierung einer Kampagne:

// Creates a Campaign object with the proper resource name and any other
// changes.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that updates the campaign, using the
// FieldMasks.allSetFieldsOf utility to derive the update mask. This mask tells
// the Google Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

In diesem Beispiel wird zuerst ein leerer Campaign-Builder erstellt und sein Ressourcenname festgelegt, damit die API weiß, welche Kampagne aktualisiert wird.

Im Beispiel wird dann FieldMasks.allSetFieldsOf() für die Kampagne aufgerufen, um automatisch eine Feldmaske zu erstellen, die alle festgelegten Felder auflistet. Sie können die zurückgegebene Maske direkt an den Aktualisierungsaufruf übergeben.

Wenn Sie mit einem vorhandenen Objekt arbeiten und einige Felder aktualisieren müssen, verwenden Sie FieldMasks.compare() so:

// Assumes existingCampaign was retrieved from a previous API call.

// Creates a new campaign based on the existing campaign and updates the
// campaign by setting its status to paused.
Campaign campaignToUpdate =
    existingCampaign.toBuilder()
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that updates the campaign, using the
// FieldMasks.compare utility to derive the update mask. This mask tells the
// Google Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaignToUpdate)
        .setUpdateMask(FieldMasks.compare(existingCampaign, campaignToUpdate))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

Wenn Sie eine Feldmaske von Grund auf neu erstellen möchten, erstellen Sie einen FieldMask-Builder und fügen Sie den snake_case-Namen jedes Felds hinzu, das Sie ändern möchten:

FieldMask fieldMask =
    FieldMask.newBuilder()
        .addPaths("status")
        .addPaths("name")
        .build();

Nachrichtenfelder und ihre Unterfelder aktualisieren

MESSAGE-Felder können Unterfelder haben (z. B. MaximizeConversions, das target_cpa_micros, cpc_bid_ceiling_micros und cpc_bid_floor_micros enthält) oder keine Unterfelder haben (z. B. ManualCpm).

Nachrichtenfelder ohne definierte Unterfelder

Wenn Sie ein MESSAGE-Feld aktualisieren, das nicht mit Unterfeldern definiert ist, verwenden Sie das Dienstprogramm FieldMasks, um eine Feldmaske zu generieren, wie im vorherigen Abschnitt beschrieben.

Nachrichtenfelder mit definierten Unterfeldern

Wenn Sie ein MESSAGE-Feld aktualisieren, für das Unterfelder definiert sind, ohne eines der Unterfelder in dieser Nachricht explizit festzulegen, müssen Sie jedes der änderbaren MESSAGE-Unterfelder manuell zur FieldMask hinzufügen, ähnlich wie beim Erstellen einer Feldmaske von Grund auf.

Ein gängiges Beispiel ist die Aktualisierung der Gebotsstrategie einer Kampagne (oneof-Feld campaign_bidding_strategy), ohne dass eines der Felder für die neue Gebotsstrategie festgelegt wird. Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne so aktualisieren, dass die Gebotsstrategie MaximizeConversions verwendet wird, ohne dass eines der Unterfelder der Gebotsstrategie festgelegt wird.

In diesem Fall reicht es nicht aus, nur die Methoden allSetFieldsOf() und compare() von FieldMasks zu verwenden, um das gewünschte Ziel zu erreichen.

Im folgenden Beispiel wird eine Feldmaske generiert, die maximize_conversions enthält. Die Google Ads API lässt jedoch keine Nachrichtenpfade auf oberster Ebene zu, die Unterfelder in einer Aktualisierungsmaske haben, um ein versehentliches Löschen von Unterfeldern zu verhindern. Sie gibt den Fehler FieldMaskError.FIELD_HAS_SUBFIELDS zurück.

Warnung: Der folgende Code erzeugt einen FieldMaskError.FIELD_HAS_SUBFIELDS-Fehler.

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(MaximizeConversions.newBuilder().build())
        .build();

// Constructs an operation using FieldMasks.allSetFieldsOf to derive the update
// mask. The field mask includes 'maximize_conversions', which produces a
// FieldMaskError.FIELD_HAS_SUBFIELDS error.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request that results in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields with
// subfields cannot be included directly in a field mask.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne richtig aktualisieren, um die Gebotsstrategie MaximizeConversions zu verwenden, ohne eines ihrer Unterfelder festzulegen. Weitere Informationen zum Zuweisen von Standard- und Portfolio-Gebotsstrategien

Erfolg: Mit dem folgenden Code wird die Gebotsstrategie der Kampagne ohne Fehler aktualisiert.

// Creates a Campaign object with the proper resource name.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .build();

// Creates a field mask from the campaign and adds the mutable subfield
// ('maximize_conversions.target_cpa_micros') on the MaximizeConversions
// bidding strategy to the field mask. Because this subfield is included in the
// field mask while excluded from the campaign object, the Google Ads API
// switches the campaign's bidding strategy oneof to MaximizeConversions with
// target_cpa_micros unset.
FieldMask fieldMask =
    FieldMasks.allSetFieldsOf(campaign).toBuilder()
        .addPaths("maximize_conversions.target_cpa_micros")
        .build();

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();

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, sie aber im Nachrichtenobjekt nicht festlegen. 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.

Der folgende Code wird ausgeführt, aber maximize_conversions.target_cpa_micros wird nicht wie beabsichtigt gelöscht:

Warnung: Mit diesem Code wird target_cpa_micros in der Gebotsstrategie MaximizeConversions nicht gelöscht.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0L.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(
            MaximizeConversions.newBuilder().setTargetCpaMicros(0L).build())
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation using FieldMasks.allSetFieldsOf to derive the
// update mask.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request that does not clear the field
// cleanly.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

Im nächsten Beispiel wird gezeigt, wie Sie das Feld target_cpa_micros in der Gebotsstrategie MaximizeConversions richtig löschen.

Erfolg: Mit dem folgenden Code wird target_cpa_micros gelöscht.

// Creates a Campaign object with the proper resource name.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .build();

// Constructs a field mask from the campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
FieldMask fieldMask =
    FieldMasks.allSetFieldsOf(campaign).toBuilder()
        .addPaths("maximize_conversions.target_cpa_micros")
        .build();

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();

Wichtiger Hinweis: Wenn Sie ein Feld löschen möchten, fügen Sie den Pfad dieses Felds explizit der FieldMask hinzu und lassen Sie das Feld im Ressourcenobjekt ungesetzt.