필드 마스크

Google Ads API에서 필드 마스크는 API 요청이 업데이트해야 하는 필드 목록을 제공하는 데 사용됩니다. 필드 마스크에 지정되지 않은 필드는 서버로 전송되더라도 무시됩니다.

FieldMaskUtil 클래스

필드 마스크를 생성하는 권장 방법은 수정된 객체에서 필드 마스크를 생성하여 처음부터 빌드하지 않아도 되는 내장 FieldMaskUtil 클래스를 사용하는 것입니다.

다음은 FieldMasks.AllSetFieldsOf 메서드를 사용하여 설정된 모든 필드를 열거하는 필드 마스크를 생성하는 캠페인 업데이트의 예입니다. 그런 다음 생성된 필드 마스크를 업데이트 호출에 직접 전달할 수 있습니다.

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

기존 객체로 작업하고 필드를 몇 개 업데이트해야 하는 경우도 있습니다. 이러한 경우 FieldMasks.FromChanges 메서드를 사용하도록 코드를 수정합니다. 이 메서드는 두 객체 간의 차이를 나타내는 필드 마스크를 생성합니다.

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

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

CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

이 API 호출은 FieldMaskError.FIELD_HAS_SUBFIELDS 오류와 함께 실패합니다. MaximizeConversions에는 하위 필드가 3개 있으므로 Google Ads API 서버는 이러한 필드의 필드 마스크가 요청에 있어야 합니다. 하지만 요청에서 이러한 필드를 설정하지 않으므로 FieldMaskUtil가 이 상황에서 필드 마스크를 올바르게 생성할 수 없습니다.

이러한 경우 다음과 같이 필드 마스크를 수동으로 수정할 수 있습니다.

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

필드 지우는 방법

Google Ads API는 일부 필드 값의 삭제를 지원합니다. 필드를 지우려면 해당 필드의 필드 마스크를 수동으로 설정해야 합니다. 필드를 기본값 (예: int64 필드의 경우 0)으로 설정해도 필드가 지워지지는 않습니다.

다음 코드 예는 MaximizeConversions 입찰 전략의 target_cpa_micros 필드를 지우는 방법을 보여줍니다.

올바른 코드

필드 마스크에서 maximize_conversions.target_cpa_micros를 설정하고 campaign.MaximizeConversions.TargetCpaMicros 필드를 설정하지 않으므로 다음 코드는 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
};

잘못된 코드

이 필드를 0으로 설정하므로 다음 코드는 target_cpa_micros 필드를 지우지 않습니다. FieldMaskUtils 및 Google Ads API 서버 모두 이 값을 무시합니다. 또한 이 경우 서버에서 값을 무시했으므로 오류가 표시되지 않을 수도 있습니다.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object. Attempt 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 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 });