Feldmasken

In der Google Ads API werden Aktualisierungen mit einer Feldmaske vorgenommen. Die Feldmaske (google.protobuf.FieldMask) enthält eine Liste mit 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 Utility-Klasse 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 das Aktualisieren 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, in der alle festgelegten Felder aufgeführt sind. Sie können die zurückgegebene Maske direkt an den Update-Aufruf übergeben.

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

// 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 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 mit target_cpa_micros, cpc_bid_ceiling_micros und cpc_bid_floor_micros) oder keine Unterfelder (z. B. ManualCpm).

Nachrichtenfelder ohne definierte Unterfelder

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

Nachrichtenfelder mit definierten Unterfeldern

Wenn Sie ein MESSAGE-Feld mit definierten Unterfeldern aktualisieren, ohne eines der Unterfelder in der Nachricht explizit festzulegen, müssen Sie jedes der änderbaren MESSAGE-Unterfelder manuell dem FieldMask hinzufügen. Das ist so, als würden Sie eine Feldmaske von Grund auf neu erstellen.

Ein häufiges Beispiel ist das Aktualisieren der Gebotsstrategie einer Kampagne (Feld oneofcampaign_bidding_strategy), ohne eines der Felder für die neue Gebotsstrategie festzulegen. Im folgenden Beispiel wird gezeigt, wie Sie eine Kampagne so aktualisieren, dass die Gebotsstrategie MaximizeConversions verwendet wird, ohne dass Unterfelder für die Gebotsstrategie festgelegt werden.

In diesem Fall reicht es nicht aus, nur die Methoden allSetFieldsOf() und compare() von FieldMasks zu verwenden.

Im folgenden Beispiel wird eine Feldmaske generiert, die maximize_conversions enthält. Die Google Ads API lässt jedoch keine Nachrichtenpfade der obersten Ebene mit Unterfeldern in einer Aktualisierungsmaske zu, um das versehentliche Löschen von Unterfeldern zu verhindern. In diesem Fall wird der Fehler FieldMaskError.FIELD_HAS_SUBFIELDS zurückgegeben.

// 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 sehen Sie, wie Sie eine Kampagne richtig aktualisieren, damit die Gebotsstrategie MaximizeConversions verwendet wird, ohne dass die zugehörigen Unterfelder festgelegt werden. Weitere Informationen zum Zuweisen von Standard- und Portfolio-Gebotsstrategien

// 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, während sie im Nachrichtenobjekt nicht festgelegt bleiben. Angenommen, Sie haben eine Kampagne, in der die Gebotsstrategie MaximizeConversions verwendet wird und für das Feld target_cpa_micros ein Wert über 0 festgelegt ist.

Der folgende Code wird ausgeführt, aber maximize_conversions.target_cpa_micros wird nicht wie vorgesehen 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 das Feld target_cpa_micros in der Gebotsstrategie MaximizeConversions richtig gelöscht wird.

// 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();