필드 마스크

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에는 세 개의 하위 필드가 있으므로 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 });