Alan maskeleri

Google Ads API'de güncellemeler alan maskesi kullanılarak yapılır. Alan maskesi (google.protobuf.FieldMask), güncelleme ile değiştirmek istediğiniz snake_case içindeki alan yollarının listesini içerir. Alan maskesinde olmayan belirtilmiş alanlar, sunucuya gönderilse bile yoksayılır.

FieldMasks yardımcı programı

Java 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.

Kampanya güncelleme örneğini aşağıda bulabilirsiniz:

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

Ardından örnek, tüm ayarlanmış alanları numaralandıran bir alan maskesini otomatik olarak oluşturmak için kampanyada FieldMasks.allSetFieldsOf() çağrısı yapar. 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 şekilde 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 bir alan maskesi oluşturmak için FieldMask oluşturucu oluşturun ve değiştirmeyi planladığınız 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ı, alt alanlara (örneğin, MaximizeConversions; target_cpa_micros, cpc_bid_ceiling_micros ve cpc_bid_floor_micros alt alanlarına sahiptir) veya alt alanlara sahip olmayabilir (örneğin, ManualCpm).

Alt alanları tanımlanmamış mesaj alanları

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

Alt alanları tanımlanmış ileti alanları

Bir iletideki alt alanların hiçbirini açıkça ayarlamadan, tanımlanmış alt alanları olan bir MESSAGE alanını güncellerken her bir değiştirilebilir MESSAGE alt alanını FieldMask'ye manuel olarak eklemeniz gerekir. Bu işlem, sıfırdan alan maskesi oluşturmaya benzer.

Bunun yaygın bir örneği, yeni teklif stratejisindeki alanlardan herhangi birini ayarlamadan bir kampanyanın teklif stratejisini (oneof alanı campaign_bidding_strategy) güncellemedir. Aşağıdaki örnekte, teklif stratejisinde herhangi bir alt alan ayarlanmadan kampanyanın MaximizeConversions teklif stratejisini kullanacak şekilde nasıl güncelleneceği gösterilmektedir.

Bu durumda, FieldMasks yöntemlerinin yalnızca allSetFieldsOf() ve compare() kullanılması amaçlanan hedefi gerçekleştirmez.

Aşağıdaki örnek, maximize_conversions içeren bir alan maskesi oluşturur. 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.

// 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, alt alanlarından herhangi birini ayarlamadan MaximizeConversions teklif stratejisini kullanmak için bir kampanyanın nasıl doğru şekilde güncelleneceği gösterilmektedir. Standart ve portföy teklifi stratejileri atama hakkında daha fazla bilgi edinin.

// 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ı ileti nesnesinde ayarlanmamış olarak bırakırken alan maskesine açıkça eklemeniz gerekir. Örneğin, MaximizeConversions teklif stratejisinin kullanıldığı bir kampanyanız olduğunu ve target_cpa_micros alanının 0 değerinden büyük bir değerle ayarlandığını varsayalım.

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

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

Sonraki örnekte, MaximizeConversions teklif stratejisinde target_cpa_micros alanının nasıl doğru şekilde temizleneceği gösterilmektedir.

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