필드 마스크

<ph type="x-smartling-placeholder">

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 필드에는 하위 필드 (예: 다음 세 가지를 포함하는 MaximizeConversions: target_cpa_micros, cpc_bid_ceiling_micros 및 cpc_bid_floor_micros)의 경우 값이 없을 수 있습니다. 전혀 (예: ManualCpm)

정의된 하위 필드가 없는 메시지 필드

하위 필드로 정의되지 않은 MESSAGE 필드를 업데이트할 때는 다음을 사용합니다. FieldMasks: 위에서 설명한 대로 필드 마스크를 생성합니다.

하위 필드가 정의된 메시지 필드

다음이 없는 하위 필드로 정의된 MESSAGE 필드를 업데이트할 때 명시적으로 해당 메시지의 하위 필드를 명시적으로 설정하려면 다음과 같이 변경 가능한 각 MESSAGE 하위 필드를 FieldMask에 추가합니다. 위의 예에서는 필드 마스크를 처음부터 만듭니다.

한 가지 일반적인 예는 새 입찰 전략의 입력란입니다. 아래 예는 사용할 수 있도록 MaximizeConversions 입찰 전략 로 확장됩니다.

이 경우 AllSetFieldsOf() 및 FromChanges() 메서드를 사용하여 FieldMasks이(가) 의도한 목표를 달성하지 못합니다.

다음 예시에서는 다음과 같은 필드 마스크를 생성합니다. 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 });

다음 예는 target_cpa_micros를 올바르게 삭제하는 방법을 보여줍니다. MaximizeConversions 입찰 전략의 필드입니다.

// 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에서 optional로 정의됩니다. protocol buffers 그러나 target_cpa_micros 드림 optional 입력란이 아닙니다. '잘못됨' 예제는 아닙니다 입찰 전략을 사용하여 target_cpa 필드를 지웁니다.