Feldmasken

In der Google Ads API wird eine Feldmaske verwendet, um eine Liste der Felder anzugeben, die durch eine API-Anfrage aktualisiert werden sollen. Alle Felder, die nicht in der Feldmaske angegeben sind, werden ignoriert, auch wenn sie an den Server gesendet werden.

Klasse „FieldMaskUtil“

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

Hier sehen Sie ein Beispiel für die Aktualisierung einer Kampagne, bei der mit der Methode FieldMasks.AllSetFieldsOf eine Feldmaske erstellt wird, in der alle festgelegten Felder aufgeführt sind. Sie können die generierte Feldmaske dann direkt an den Update-Aufruf übergeben.

// Update campaign by setting its status to paused, and "Search network" to false.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    NetworkSettings = new NetworkSettings()
    {
        TargetSearchNetwork = false
    }
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

// Update the campaign.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

Manchmal müssen Sie mit einem vorhandenen Objekt arbeiten und einige Felder aktualisieren. In solchen Fällen würden Sie den Code so ändern, dass stattdessen die Methode FieldMasks.FromChanges verwendet wird. Mit dieser Methode wird eine Feldmaske generiert, die den Unterschied zwischen zwei Objekten darstellt.

Campaign existingCampaign;

// Obtain existingCampaign from elsewhere.
...

// Create a new campaign based off the existing campaign for update.
Campaign campaignToUpdate = new Campaign(existingCampaign);

// Update campaign by setting its status to paused, and "Search network" to
// false.
campaignToUpdate.Status = CampaignStatus.Paused;
campaignToUpdate.NetworkSettings = new NetworkSettings()
{
    TargetSearchNetwork = false
}

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.FromChanges(existingCampaign, campaignToUpdate)
};

Umgang mit FieldMaskError.FIELD_HAS_SUBFIELDS-Fehlern

In seltenen Fällen müssen Sie möglicherweise ein Feld festlegen, ohne die Unterfelder dieses Typs zu aktualisieren. Dazu ein Beispiel:

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
};

CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

Dieser API-Aufruf schlägt mit dem Fehler FieldMaskError.FIELD_HAS_SUBFIELDS fehl. Da MaximizeConversions drei Unterfelder hat, erwartet der Google Ads API-Server, dass Feldmasken für diese Felder in der Anfrage vorhanden sind. FieldMaskUtil kann in dieser Situation jedoch keine Feldmasken korrekt generieren, da diese Felder in der Anfrage nicht festgelegt werden.

In solchen Fällen können Sie die Feldmaske manuell bearbeiten:

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
// Only include 'maximize_conversions.target_cpa_micros' in the field mask
// as it is the only mutable subfield on MaximizeConversions when used as a
// standard bidding strategy.
//
// Learn more about standard and portfolio bidding strategies here:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

Felder leeren

In der Google Ads API können einige Feldwerte gelöscht werden. Wenn Sie ein Feld leeren möchten, müssen Sie die Feldmaske für dieses Feld manuell festlegen. Wenn Sie ein Feld auf seinen Standardwert festlegen (z. B. null für ein int64-Feld), wird das Feld nicht gelöscht.

Das folgende Codebeispiel zeigt, wie das Feld target_cpa_micros der Gebotsstrategie MaximizeConversions gelöscht wird.

Richtiger Code

Im folgenden Code wird das Feld target_cpa_micros gelöscht, da wir maximize_conversions.target_cpa_micros in der Feldmaske festlegen und das Feld campaign.MaximizeConversions.TargetCpaMicros nicht festlegen.

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

Falscher Code

Im folgenden Code wird das Feld target_cpa_micros nicht gelöscht, da wir es auf null setzen. Sowohl FieldMaskUtils als auch der Google Ads API-Server ignorieren diesen Wert. Außerdem erhalten Sie in diesem Fall möglicherweise keine Fehlermeldung, da der Wert vom Server ignoriert wurde.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object. Attempt to clear the target_cpa_micros field by setting it to 0.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
    {
        TargetCpaMicros = 0
    }
};

// Constructs an operation, using the FieldMasks' AllSetFieldsOf utility to
// derive the update mask. However, the field mask will NOT include
// 'maximize_conversions.target_cpa_micros'.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that will succeed but will NOT update
// the 'target_cpa_micros' field because 'maximize_conversions.target_cpa_micros'
// was not included in the field mask.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });