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 „FieldMasks“

Die empfohlene Methode zum Generieren von Feldmasken in der .NET-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 sehen Sie ein Beispiel für die Aktualisierung einer Kampagne, bei der mit der Methode FieldMasks.AllSetFieldsOf eine Feldmaske mit allen festgelegten Feldern erstellt wird. 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. Verwenden Sie in solchen Fällen stattdessen die Methode FieldMasks.FromChanges. Mit dieser Methode wird eine Feldmaske generiert, die den Unterschied zwischen zwei Objekten darstellt:

Campaign existingCampaign;

// Obtain existingCampaign from an earlier API call.

// Create a new campaign based on 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)
};

FieldMaskError.FIELD_HAS_SUBFIELDS-Fehler beheben

In seltenen Fällen müssen Sie möglicherweise ein Nachrichtenfeld festlegen, ohne seine Unterfelder 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 Unterfelder hat, erwartet der Google Ads API-Server, dass Feldmasken für die veränderlichen Unterfelder in der Anfrage vorhanden sind. FieldMasks kann in diesem Fall jedoch keine Masken für Unterfelder automatisch generieren, da in der Anfrage keine Unterfelder festgelegt sind.

In solchen Fällen können Sie Pfade manuell zu fieldMask.Paths hinzufügen (RepeatedField<string>):

// 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 at:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.Add("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 löschen

In der Google Ads API können einige Feldwerte gelöscht werden. Wenn Sie ein Feld löschen möchten, müssen Sie es manuell in die Feldmaske einfügen und das Feld im Ressourcenobjekt nicht festlegen. Wenn Sie ein Feld auf seinen Standardwert festlegen (z. B. 0 für ein int64-Feld), wird das Feld nicht geleert.

Das folgende Codebeispiel zeigt, wie das Feld target_cpa_micros einer MaximizeConversions-Gebotsstrategie gelöscht wird:

Richtiger Code

Im folgenden Code wird das Feld target_cpa_micros gelöscht, da maximize_conversions.target_cpa_micros der Feldmaske hinzugefügt wird, ohne die Eigenschaft campaign.MaximizeConversions.TargetCpaMicros festzulegen:

// 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
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.Add("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 es auf 0 festgelegt wird. Sowohl das FieldMasks-Tool als auch der Google Ads API-Server ignorieren diesen Wert, wenn TargetCpaMicros gleich 0 ist oder wenn der Pfad aus der Maske entfernt wird. Der Server gibt keinen Fehler zurück:

// Creates a campaign with the proper resource name and a
// MaximizeConversions object. Attempts 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 FieldMasks.AllSetFieldsOf to derive the
// update mask.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that succeeds without clearing
// the previous 'target_cpa_micros' value cleanly.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });