フィールド マスク

<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 オブジェクトを作成します。次に、そのリソース名を 更新するキャンペーンを正確に把握できます

この例では、キャンペーンで FieldMasks.AllSetFieldsOf メソッドを使用します。 は、設定されたすべてのフィールドを列挙するフィールド マスクを自動的に生成します。その後、 返されたマスクを update 呼び出しに直接渡します。

場合によっては、既存のオブジェクトを操作して、いくつかのフィールドを更新する必要があります。 その場合は、次のようにコードを変更します。

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 には、次の 3 つがあります。 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
};

フィールドをクリアする

一部のフィールドは明示的にクリアできます。上記の例と同様に、次の操作を行う必要があります。 フィールド マスクに明示的に追加することもできます。たとえば、24 時間 365 日の 「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 フィールドを消去します。