Feldmasken

In der Google Ads API wird eine Feldmaske verwendet, um eine Liste von Feldern 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 Dienstprogrammklasse FieldMasks. Damit können Sie Feldmasken aus einem geänderten Objekt generieren, anstatt sie von Grund auf neu zu erstellen.

Hier ist ein Beispiel für die Aktualisierung einer Kampagne, bei der die Methode FieldMasks.AllSetFieldsOf verwendet wird, um eine Feldmaske zu erstellen, in der alle festgelegten Felder aufgeführt sind. Sie können die generierte Feldmaske dann direkt an den Aktualisierungsaufruf ü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. Diese Methode generiert eine Feldmaske, 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 verarbeiten

In seltenen Fällen müssen Sie möglicherweise ein Nachrichtenfeld festlegen, ohne eines seiner 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 änderbaren Unterfelder in der Anfrage vorhanden sind. FieldMasks kann in dieser Situation jedoch keine Unterfeldmasken automatisch generieren, da in der Anfrage keine Unterfelder festgelegt sind.

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

// 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

Die Google Ads API unterstützt das Löschen einiger Feldwerte. Wenn Sie ein Feld löschen möchten, müssen Sie es manuell in die Feldmaske aufnehmen und das Feld im Ressourcenobjekt nicht festlegen. Wenn Sie ein Feld auf seinen Standardwert setzen (z. B. 0 für ein int64-Feld), wird das Feld nicht gelöscht.

Im folgenden Codebeispiel wird gezeigt, wie das Feld target_cpa_micros einer MaximizeConversions-Gebotsstrategie gelöscht wird:

Richtiger Code

Mit dem folgenden Code wird das Feld target_cpa_micros gelöscht, da maximize_conversions.target_cpa_micros der Feldmaske hinzugefügt wird, ohne dass das Attribut campaign.MaximizeConversions.TargetCpaMicros festgelegt wird:

// 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

Mit dem folgenden Code wird das Feld target_cpa_micros nicht gelöscht, da das Feld auf 0 gesetzt wird. Sowohl das Dienstprogramm FieldMasks als auch der Google Ads API-Server ignorieren diesen Wert, wenn TargetCpaMicros den Wert 0 hat oder der Pfad in der Maske weggelassen 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 });