Alan maskeleri

Google Ads API'de, bir API isteğinin güncellemesi gereken alanların listesini sağlamak için alan maskesi kullanılır. Alan maskesinde belirtilmeyen tüm alanlar, sunucuya gönderilmiş olsalar bile yoksayılır.

FieldMasks sınıfı

.NET istemci kitaplığında alan maskeleri oluşturmanın önerilen yolu, yerleşik FieldMasks yardımcı sınıfını kullanmaktır. Bu sınıf, alan maskelerini sıfırdan oluşturmak yerine değiştirilmiş bir nesneden oluşturmanıza olanak tanır.

Aşağıda, tüm ayarlanmış alanları numaralandıran bir alan maskesi oluşturmak için FieldMasks.AllSetFieldsOf yöntemini kullanan bir kampanyayı güncelleme örneği verilmiştir. Ardından, oluşturulan alan maskesini doğrudan güncelleme çağrısına iletebilirsiniz:

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

Bazen mevcut bir nesneyle çalışmanız ve birkaç alanı güncellemeniz gerekebilir. Bu gibi durumlarda bunun yerine FieldMasks.FromChanges yöntemini kullanın. Bu yöntem, iki nesne arasındaki farkı temsil eden bir alan maskesi oluşturur:

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 hatalarını ele alma

Nadiren de olsa, alt alanlarını güncellemeden bir mesaj alanı ayarlamanız gerekebilir. Aşağıdaki örneği inceleyelim:

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

Bu API çağrısı FieldMaskError.FIELD_HAS_SUBFIELDS hatasıyla başarısız olur. MaximizeConversions alt alanları olduğundan Google Ads API sunucusu, istekte değiştirilebilir alt alanlar için alan maskelerinin bulunmasını bekler. Ancak istekte herhangi bir alt alan ayarlanmadığı için FieldMasks bu durumda alt alan maskelerini otomatik olarak oluşturamaz.

Bu gibi durumlarda, fieldMask.Paths'ya (RepeatedField<string>) manuel olarak yollar ekleyebilirsiniz:

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

Alanları temizle

Google Ads API, bazı alan değerlerinin temizlenmesini destekler. Bir alanı temizlemek için bu alanı, kaynak nesnesinde ayarlanmamış olarak bırakırken alan maskesine manuel olarak eklemeniz gerekir. Bir alanı varsayılan değerine ayarlamak (ör. int64 alanı için 0) alanı temizlemez.

Aşağıdaki kod örneğinde, bir MaximizeConversions teklif stratejisinin target_cpa_micros alanının nasıl temizleneceği gösterilmektedir:

Doğru kod

Aşağıdaki kod, campaign.MaximizeConversions.TargetCpaMicros özelliğini ayarlamadan alan maskesine maximize_conversions.target_cpa_micros eklediği için target_cpa_micros alanını temizler:

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

Yanlış kod

Aşağıdaki kod, alanı 0 olarak ayarladığından target_cpa_micros alanını temizlemez. Hem FieldMasks yardımcı programı hem de Google Ads API sunucusu, TargetCpaMicros değeri 0 olduğunda veya yol maskeden çıkarıldığında bu değeri yoksayar ve sunucu hata döndürmez:

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