필드 마스크

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

FieldMasks 클래스

.NET 클라이언트 라이브러리에서 필드 마스크를 생성하는 가장 좋은 방법은 기본 제공 FieldMasks 유틸리티 클래스를 사용하는 것입니다. 이 클래스를 사용하면 처음부터 빌드하는 대신 수정된 객체에서 필드 마스크를 생성할 수 있습니다.

다음은 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 an earlier API call.

// Create a new campaign based on 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 서버는 변경 가능한 하위 필드의 필드 마스크가 요청에 있어야 합니다. 하지만 요청에서 하위 필드를 설정하지 않으므로 FieldMasks가 이 상황에서 하위 필드 마스크를 자동으로 생성할 수 없습니다.

이 경우 fieldMask.Paths (RepeatedField<string>)에 경로를 수동으로 추가할 수 있습니다.

// 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 at:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.Add("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 필드를 지우는 방법을 보여줍니다.

올바른 코드

다음 코드는 campaign.MaximizeConversions.TargetCpaMicros 속성을 설정하지 않고 필드 마스크에 maximize_conversions.target_cpa_micros를 추가하므로 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
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.Add("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 필드를 지우지 않습니다. TargetCpaMicros이 0이거나 마스크에서 경로가 생략된 경우 FieldMasks 유틸리티와 Google Ads API 서버는 이 값을 무시하며 서버는 오류를 반환하지 않습니다.

// Creates a campaign with the proper resource name and a
// MaximizeConversions object. Attempts 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 FieldMasks.AllSetFieldsOf to derive the
// update mask.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that succeeds without clearing
// the previous 'target_cpa_micros' value cleanly.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });