Полевые маски

В Google Ads API обновления выполняются с использованием маски поля. В маске поля перечислены все поля, которые вы собираетесь изменить при обновлении, а любые указанные поля, которых нет в маске поля, будут игнорироваться, даже если они будут отправлены на сервер.

ПолеМаскаУтилита

Рекомендуемый способ создания масок полей — использование нашей встроенной утилиты маски полей, которая позволяет создавать маски полей из измененного объекта, а не создавать их с нуля.

Вот пример обновления кампании:

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

В этом примере сначала создается пустой объект Campaign , а затем задается имя его ресурса, чтобы API знал, какая кампания обновляется.

В примере используется метод FieldMasks.allSetFieldsOf() кампании для автоматического создания маски поля, перечисляющей все установленные поля. Затем вы можете передать возвращенную маску непосредственно в вызов обновления.

Если вам нужно поработать с существующим объектом для обновления нескольких полей, вы можете изменить код следующим образом:

Campaign existingCampaign;  // Obtains existingCampaign from elsewhere. ...  // Creates a new campaign based off 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 will update 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));

Чтобы создать маску поля с нуля, сначала необходимо создать объект FieldMask , а затем добавить к объекту имя каждого поля, которое вы собираетесь изменить.

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

Обновление полей сообщений и их подполей

Поля MESSAGE могут иметь подполя (например, MaximizeConversions , у которого их три: target_cpa_micros , cpc_bid_ceiling_micros и cpc_bid_floor_micros ) или вообще не иметь их (например, ManualCpm ).

Поля сообщений без определенных подполей

При обновлении поля MESSAGE , которое не определено какими-либо подполями, используйте FieldMaskUtil для создания маски поля, как описано выше.

Поля сообщений с определенными подполями

При обновлении поля MESSAGE , которое определено с подполями, без явной установки каких-либо подполей в этом сообщении, вы должны вручную добавить каждое из изменяемых подполей MESSAGE в FieldMask , аналогично приведенному выше примеру, который создает маску поля с нуля.

Одним из распространенных примеров является обновление стратегии назначения ставок кампании без задания каких-либо полей в новой стратегии назначения ставок. В приведенном ниже примере показано, как обновить кампанию для использования стратегии назначения ставок MaximizeConversions , не задавая никаких подполей в стратегии назначения ставок.

В этом случае использование методов allSetFieldsOf() и compare() FieldMaskUtil не достигает намеченной цели.

В следующем примере создается маска поля, включающая maximize_conversions . Однако API Google Рекламы не позволяет использовать такое поведение для предотвращения случайной очистки полей и выдает ошибку FieldMaskError.FIELD_HAS_SUBFIELDS .

// 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 the FieldMasks' allSetFieldsOf utility to // derive the update mask. The field mask will include 'maximize_conversions`, // which will produce 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 will result in a // FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot // be included in a field mask. MutateCampaignsResponse response =     campaignServiceClient.mutateCampaigns(         customerId.toString(), Collections.singletonList(operation));

В следующем примере показано, как правильно обновить кампанию для использования стратегии назначения ставок MaximizeConversions без установки каких-либо ее подполей.

// 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 existing campaign and adds all of the mutable // fields (only one in this case) on the MaximizeConversions bidding strategy to // the field mask. Because this field is included in the field mask but // excluded from the campaign object, the Google Ads API will set the campaign's // bidding strategy to a MaximizeConversions object without any of its subfields // set. FieldMask fieldMask = FieldMasks.allSetFieldsOf(campaign)     .toBuilder()     // 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 here:     // https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies     .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();

Очистка полей

Некоторые поля можно очистить явно. Как и в приведенном выше примере, вы должны явно добавить эти поля в маску поля. Например, предположим, что у вас есть кампания, в которой используется стратегия назначения ставок MaximizeConversions , и в поле target_cpa_micros установлено значение больше 0.

Выполняется следующий код; однако maximize_conversions.target_cpa_micros не будет добавлен в маску поля, поэтому в поле target_cpa_micros не будет внесено никаких изменений:

// Creates a campaign with the proper resource name and a MaximizeConversions // object with target_cpa_micros set to 0. Campaign campaign =     Campaign.newBuilder()         .setResourceName(ResourceNames.campaign(customerId, campaignId))         .setMaximizeConversions(             MaximizeConversions.newBuilder().setTargetCpa(0).build())         .setStatus(CampaignStatus.PAUSED)         .build();  // Constructs an operation, using the FieldMasks' allSetFieldsOf utility to // derive the update mask. However, the field mask will NOT include // 'maximize_conversions.target_cpa_micros'. CampaignOperation operation =     CampaignOperation.newBuilder()         .setUpdate(campaign)         .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))         .build();  // Sends the operation in a mutate request that will succeed but will NOT update // the 'target_cpa_micros' field because // 'maximize_conversions.target_cpa_micros' was not included in the field mask. MutateCampaignsResponse response =     campaignServiceClient.mutateCampaigns(         customerId.toString(), Collections.singletonList(operation));

В следующем примере показано, как правильно очистить поле target_cpa_micros в стратегии назначения ставок MaximizeConversions .

// 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 existing campaign and adds the // 'maximize_conversions.target_cpa_micros' field to the field mask, which will // clear 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();

Обратите внимание, что приведенный выше «неправильный» пример работает должным образом для полей, которые определены как optional в protocol buffers API Google Рекламы. Но поскольку поле target_cpa_micros не является optional , в «неправильном» примере стратегия назначения ставок не обновляется для очистки поля target_cpa .