Google Ads API에서 업데이트는 필드 마스크를 사용하여 이루어집니다. 필드 마스크는 업데이트로 변경하려는 모든 필드를 나열하며, 필드 마스크에 없는 지정된 필드는 서버에 전송되더라도 무시됩니다.
FieldMaskUtil
필드 마스크를 생성할 때 권장되는 방법은 내장된 필드 마스크 유틸리티를 사용하는 것입니다. 이 유틸리티를 사용하면 수정된 객체를 처음부터 빌드하는 대신 이 객체에서 필드 마스크를 생성할 수 있습니다.
다음은 캠페인을 업데이트하는 예입니다.
// 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 });
먼저 빈 Campaign
객체를 만듭니다. 그런 다음 API가 업데이트할 캠페인을 정확하게 알 수 있도록 리소스 이름을 설정합니다.
이 예시에서는 캠페인에서 FieldMasks.AllSetFieldsOf
메서드를 사용하여 설정된 모든 필드를 열거하는 필드 마스크를 자동으로 생성합니다. 그런 다음 반환된 마스크를 직접 업데이트 호출에 전달할 수 있습니다.
경우에 따라 기존 객체로 작업하고 몇 개의 필드를 업데이트해야 할 수도 있습니다. 이러한 경우 다음과 같이 코드를 수정합니다.
Campaign existingCampaign;
// Obtain existingCampaign from elsewhere.
...
// Create a new campaign based off 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)
};
필드 마스크를 처음부터 만들려면 먼저 FieldMask
객체를 만든 다음 변경하려는 모든 필드의 이름으로 채워진 배열을 만들고 마지막으로 배열 콘텐츠를 필드 마스크의 Path
필드에 추가합니다.
FieldMask fieldMask = new FieldMask();
fieldMask.Paths.AddRange(new string[] { "status", "name" });
메시지 필드 및 하위 필드 업데이트
MESSAGE
필드에는 하위 필드가 있을 수 있으며 (예: target_cpa_micros
, cpc_bid_ceiling_micros
, cpc_bid_floor_micros
3개가 있는 MaximizeConversions
), 아예 포함되지 않을 수도 있습니다 (예: ManualCpm
).
정의된 하위 필드가 없는 메시지 필드
하위 필드로 정의되지 않은 MESSAGE
필드를 업데이트할 때는 위에서 설명한 대로 FieldMasks
를 사용하여 필드 마스크를 생성합니다.
하위 필드가 정의된 메시지 필드
해당 메시지의 하위 필드를 명시적으로 설정하지 않고 하위 필드로 정의된 MESSAGE
필드를 업데이트할 때는 필드 마스크를 처음부터 만드는 위 예시와 유사하게 각 변경 가능한 MESSAGE
하위 필드를 각각 FieldMask
에 수동으로 추가해야 합니다.
한 가지 일반적인 예는 새 입찰 전략에 필드를 설정하지 않고 캠페인의 입찰 전략을 업데이트하는 것입니다. 아래 예에서는 입찰 전략의 하위 필드를 설정하지 않고 MaximizeConversions
입찰 전략을 사용하도록 캠페인을 업데이트하는 방법을 보여줍니다.
이 경우 FieldMasks
의 AllSetFieldsOf()
및 FromChanges()
메서드를 사용하면 의도한 목표를 달성할 수 없습니다.
다음 예시에서는 maximize_conversions
를 포함하는 필드 마스크를 생성합니다. 하지만 Google Ads API에서는 이러한 동작이 실수로 필드를 지우고 FieldMaskError.FIELD_HAS_SUBFIELDS
오류를 생성하는 것을 방지하도록 허용하지 않습니다.
// 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()
};
// 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 = new CampaignOperation()
{
Update = campaign,
UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};
// 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 = campaignService.MutateCampaigns(
customerId.ToString(), new CampaignOperation[] { operation });
다음 예는 하위 필드를 설정하지 않고 MaximizeConversions
입찰 전략을 사용하도록 캠페인을 올바르게 업데이트하는 방법을 보여줍니다.
// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
ResourceName = ResourceNames.Campaign(customerId, campaignId),
};
// Creates a field mask from the existing campaign and adds all of the fields
// on the MaximizeConversions bidding strategy to the field mask. Because these
// fields are 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 with none of its subfields set.
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 here:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.AddRange(new string[] {
"maximize_conversions.target_cpa_micros",
});
// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation = new CampaignOperation()
{
Update = campaign,
UpdateMask = fieldMask
};
필드 지우기
일부 필드는 명시적으로 지울 수 있습니다. 위의 예와 마찬가지로 이러한 필드를 필드 마스크에 명시적으로 추가해야 합니다. 예를 들어 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 = new Campaign()
{
ResourceName = ResourceNames.Campaign(customerId, campaignId),
MaximizeConversions = new MaximizeConversions()
{
TargetCpaMicros = 0
}
};
// 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 = new CampaignOperation()
{
Update = campaign,
UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};
// 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 = campaignService.MutateCampaigns(
customerId.ToString(), new CampaignOperation[] { operation });
다음 예에서는 MaximizeConversions
입찰 전략에서 target_cpa_micros
필드를 올바르게 삭제하는 방법을 보여줍니다.
// 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 will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.AddRange(new string[] {
"maximize_conversions.target_cpa_micros",
});
// Creates an operation to update the campaign with the specified field.
CampaignOperation operation = new CampaignOperation()
{
Update = campaign,
UpdateMask = fieldMask
};
위의 '잘못된' 예는 Google Ads API protocol buffers
에서
optional
로 정의된 필드에 의도된 대로
작동합니다.
하지만 target_cpa_micros
는 optional
필드가 아니므로 '잘못된' 예시는 target_cpa
필드를 지우도록 입찰 전략을 업데이트하지 않습니다.