フィールド マスク

Google Ads API では、フィールド マスクを使用して更新を行います。フィールド マスクには、 更新で変更するすべてのフィールドと、指定した フィールド マスクに存在しない文字は、サーバーに送信されても無視されます。

FieldMaskUtil

フィールド マスクを生成するには、組み込みのフィールド マスクを使用することをおすすめします。 このユーティリティを使用すると、変更せずに変更されたオブジェクトからフィールド マスクを生成できます。 ゼロから構築することもあります

キャンペーンを更新する例を次に示します。

// Creates a Campaign object with the proper resource name and any other changes.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that will update the campaign, using the FieldMasks'
// allSetFieldsOf utility to derive the update mask. This mask tells the Google
// Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

この例では、まず空の Campaign オブジェクトを作成してから、そのリソースを設定します。 更新するキャンペーンを API が認識できるようにする必要があります。

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

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

Campaign existingCampaign;

// Obtains existingCampaign from elsewhere.
...

// Creates a new campaign based off the existing campaign and updates the
// campaign by setting its status to paused.
Campaign campaignToUpdate =
    existingCampaign.toBuilder()
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that will update the campaign, using the FieldMasks'
// compare utility to derive the update mask. This mask tells the Google Ads API
// which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaignToUpdate)
        .setUpdateMask(FieldMasks.compare(existingCampaign, campaignToUpdate))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

フィールド マスクをゼロから作成するには、まず FieldMask 次に、変更する各フィールドの名前を 渡されます。

FieldMask fieldMask =
    FieldMask.newBuilder()
        .addPaths("status")
        .addPaths("name")
        .build();

メッセージ フィールドとそのサブフィールドの更新

MESSAGE フィールドにはサブフィールド（ MaximizeConversions には、次の 3 つがあります。 target_cpa_micros, cpc_bid_ceiling_micros、cpc_bid_floor_micros など）または、 すべて含めないでください（ManualCpm など）。

サブフィールドが定義されていないメッセージ フィールド

サブフィールドで定義されていない MESSAGE フィールドを更新する場合は、次のコマンドを使用します。 FieldMaskUtil を使用してフィールド マスクを生成します。

サブフィールドが定義されたメッセージ フィールド

サブフィールドで定義されている MESSAGE フィールドを更新する場合 そのメッセージのサブフィールドを明示的に設定する場合は、 次のように、変更可能な各 MESSAGE サブフィールドを FieldMask に追加します。 ゼロからフィールド マスクを作成する上記の例です。

一般的な例は、何も設定せずにキャンペーンの入札戦略を更新することです。 新しい入札戦略のフィールドが表示されます下の例では、 キャンペーンを更新して MaximizeConversions 入札戦略 入札戦略でサブフィールドを設定せずに

この場合、allSetFieldsOf() メソッドと compare() メソッドを使って、 FieldMaskUtil で目的の目標を達成できません。

次の例では、次のフィールドを含むフィールド マスクを生成します。 maximize_conversions。ただし Google Ads API では、このような動作は許可されません。 誤ってフィールドがクリアされることがなくなり、 FieldMaskError.FIELD_HAS_SUBFIELDS エラーが発生します。

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = Campaign.newBuilder()
    .setResourceName(ResourceNames.campaign(customerId, campaignId))
    .setMaximizeConversions(MaximizeConversions.newBuilder().build())
    .build();

// 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 =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// 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 =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

次のサンプルは、 サブフィールドを設定しない「MaximizeConversions」入札戦略。

// Creates a Campaign object with the proper resource name.
Campaign campaign = Campaign.newBuilder()
    .setResourceName(ResourceNames.campaign(customerId, campaignId))
    .build();

// Creates a field mask from the existing campaign and adds all of the mutable
// fields (only one in this case) on the MaximizeConversions bidding strategy to
// the field mask. Because this field is 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 without any of its subfields
// set.
FieldMask fieldMask = FieldMasks.allSetFieldsOf(campaign)
    .toBuilder()
    // 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
    .addPaths("maximize_conversions.target_cpa_micros")
    .build();

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();

フィールドをクリアする

一部のフィールドは明示的にクリアできます。上記の例と同様に、次の操作を行う必要があります。 フィールド マスクに明示的に追加することもできます。たとえば、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 =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(
            MaximizeConversions.newBuilder().setTargetCpa(0).build())
        .setStatus(CampaignStatus.PAUSED)
        .build();

// 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 =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// 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 =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

次の例は、target_cpa_micros を適切にクリアする方法を示しています。 入札戦略「MaximizeConversions」のフィールドで、

// Creates a Campaign object with the proper resource name.
Campaign campaign = Campaign.newBuilder()
    .setResourceName(ResourceNames.campaign(customerId, campaignId))
    .build();

// 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)
    .toBuilder()
    .addPaths("maximize_conversions.target_cpa_micros")
    .build();

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask))
        .build();

「不正解」なのは上記の例は、名前フィールドが Google Ads API で optional として定義されています。 protocol buffers。 しかし、 target_cpa_micros optional フィールドでない場合、「不正解」更新されてはいませんが、 入札戦略の target_cpa フィールドを消去します。