フィールド マスク

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 メソッドを使用するようにコードを変更します。このメソッドは、2 つのオブジェクト間の違いを表すフィールド マスクを生成します。

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

コードが誤っています

次のコードでは、target_cpa_micros フィールドをゼロに設定しているため、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 });