Alan maskeleri

Google Ads API'de güncellemeler alan maskesi kullanılarak yapılır. Alan maskesi (google.protobuf.FieldMask), snake_case içinde güncellemeyle değiştirmek istediğiniz alan yollarının listesini içerir. Alan maskesinde bulunmayan tüm belirtilen alanlar, sunucuya gönderilse bile yoksayılır.

FieldMasks yardımcı programı

Java istemci kitaplığında alan maskeleri oluşturmak için önerilen yöntem, 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.

Bir kampanyayı güncellemeye ilişkin örnek:

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

Bu örnekte önce boş bir Campaign oluşturucu oluşturulur ve API'nin hangi kampanyanın güncellendiğini bilmesi için kaynak adı ayarlanır.

Örnek, daha sonra kampanyada FieldMasks.allSetFieldsOf() yöntemini çağırarak tüm ayarlanmış alanları listeleyen bir alan maskesini otomatik olarak oluşturur. Döndürülen maskeyi doğrudan güncelleme çağrısına iletebilirsiniz.

Mevcut bir nesneyle çalışmanız ve birkaç alanı güncellemeniz gerekiyorsa FieldMasks.compare() öğesini aşağıdaki gibi kullanın:

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

Sıfırdan alan maskesi oluşturmak için bir FieldMask oluşturucu oluşturun ve değiştirmek istediğiniz her alanın snake_case adını ekleyin:

FieldMask fieldMask =
    FieldMask.newBuilder()
        .addPaths("status")
        .addPaths("name")
        .build();

Mesaj alanlarını ve alt alanlarını güncelleme

MESSAGE alanlarının alt alanları olabilir (ör. target_cpa_micros, cpc_bid_ceiling_micros ve cpc_bid_floor_micros alt alanlarına sahip MaximizeConversions) veya alt alanları olmayabilir (ör. ManualCpm).

Tanımlanmış alt alanları olmayan mesaj alanları

Herhangi bir alt alanla tanımlanmamış bir MESSAGE alanını güncellerken önceki bölümde açıklandığı gibi bir alan maskesi oluşturmak için FieldMasks yardımcı programını kullanın.

Tanımlanmış alt alanları olan mesaj alanları

Alt alanları tanımlanmış bir MESSAGE alanını, bu mesajdaki alt alanlardan herhangi birini açıkça ayarlamadan güncellerken değiştirilebilir MESSAGE alt alanlarının her birini FieldMask alanına manuel olarak eklemeniz gerekir. Bu işlem, sıfırdan alan maskesi oluşturmaya benzer.

Sık karşılaşılan bir örnek, yeni teklif stratejisindeki alanlardan hiçbirini ayarlamadan bir kampanyanın teklif stratejisini (oneof alanı campaign_bidding_strategy) güncellemektir. Aşağıdaki örnekte, teklif stratejisindeki alt alanlardan hiçbirini ayarlamadan MaximizeConversions teklif stratejisini kullanmak için bir kampanyanın nasıl güncelleneceği gösterilmektedir.

Bu durumda, FieldMasks sınıfının yalnızca allSetFieldsOf() ve compare() yöntemlerini kullanmak istenen amaca ulaşmak için yeterli olmaz.

Aşağıdaki örnekte, maximize_conversions içeren bir alan maskesi oluşturulmaktadır. Ancak Google Ads API, güncelleme maskesinde alt alanları olan üst düzey mesaj yollarına izin vermez (alt alanların yanlışlıkla temizlenmesini önlemek için) ve FieldMaskError.FIELD_HAS_SUBFIELDS hatası döndürür.

Uyarı: Aşağıdaki kod FieldMaskError.FIELD_HAS_SUBFIELDS hatasına neden olur.

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

Aşağıdaki örnekte, bir kampanyanın alt alanlarından herhangi birini ayarlamadan MaximizeConversions teklif stratejisini kullanacak şekilde nasıl doğru şekilde güncelleneceği gösterilmektedir. Standart ve portföy teklifi stratejileri atama hakkında daha fazla bilgi edinin.

Başarılı: Aşağıdaki kod, kampanya teklif stratejisini hatasız bir şekilde günceller.

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

Alanları temizle

Bazı alanlar açıkça temizlenebilir. Önceki örneğe benzer şekilde, bu alanları alan maskesine açıkça eklemeniz ve mesaj nesnesinde ayarlanmamış olarak bırakmanız gerekir. Örneğin, MaximizeConversions teklif stratejisini kullanan bir kampanyanız olduğunu ve target_cpa_micros alanının 0 değerinden daha yüksek bir değere ayarlandığını varsayalım.

Aşağıdaki kod çalışır ancak maximize_conversions.target_cpa_micros, amaçlandığı gibi temizlenmez:

Uyarı: Bu kod, MaximizeConversions teklif stratejisindeki target_cpa_micros değerini temizlemez.

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

Aşağıdaki örnekte, MaximizeConversions teklif stratejisindeki target_cpa_micros alanının nasıl doğru şekilde temizleneceği gösterilmektedir.

Başarılı: Aşağıdaki kod target_cpa_micros öğesini temizler.

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

Önemli nokta: Bir alanı temizlemek istiyorsanız ilgili alanın yolunu FieldMask öğesine açıkça ekleyin ve kaynak nesnesinde alanı ayarlanmamış olarak bırakın.