このページは Cloud Translation API によって翻訳されました。

フィールドマスク

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

FieldMasks ユーティリティ

フィールドマスクを生成するには、組み込みのフィールドマスクを使用することをおすすめします。ユーティリティ (FieldMasks), これにより、変更したオブジェクトからフィールドマスクを生成できます。一から作成する必要があります

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

my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    status => PAUSED,
    networkSettings =>
      Google::Ads::GoogleAds::V17::Resources::NetworkSettings->new({
        targetSearchNetwork => "false"
      })
    });

my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

この例では、まずリソース名を設定して Campaign オブジェクトを作成します。 ResourceNames ユーティリティを使用して API に認識させる更新するキャンペーンが表示されます

この例では、 FieldMasks::all_set_fields_of() メソッドを使用して、すべてのフィールドが列挙されるフィールドマスクを設定します。返されたマスクを update 呼び出しに直接渡すことができます。

FieldMasks::all_set_fields_of() は、次の場合のコンビニエンスメソッドです。 FieldMasks::field_mask()。渡されたオブジェクトと、同じクラスの空のオブジェクトを比較します。したがって、使用することもできますが、

field_mask(Google::Ads::GoogleAds::V17::Resources::Campaign->new({}), $campaign)

all_set_fields_of($campaign) の代わりに使用します。

手動でマスクを作成する

フィールドマスクをゼロから作成するには、まず Google::Ads::GoogleAds::Common::FieldMask 次に、すべてのフィールド名が入った配列参照を作成します最後に、配列参照をフィールドマスクの paths フィールド。

my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
    paths => ["status", "name"]
  });

オブジェクトフィールドとそのサブフィールドの更新

オブジェクトフィールドには、サブフィールド（ MaximizeConversions: 次の 3 つがあります。 target_cpa_micros、cpc_bid_ceiling_micros、cpc_bid_floor_micros）。または指定する必要はありません（例: ManualCpm）。

サブフィールドが定義されていないオブジェクトフィールド

Perl のオブジェクトフィールドは、クライアントの protobuf MESSAGE と同等です。使用できます。定義されていないオブジェクトフィールドを更新する場合任意のサブフィールドを含む場合は、次のように FieldMasks ユーティリティを使用してフィールドマスクを生成します。使用できます。

サブフィールドが定義されたオブジェクトフィールド

サブフィールドで定義されているオブジェクトフィールドを明示的に指定せずに更新する場合設定するには、各サブフィールドを手動で追加する必要があります。上記の例のように、変更可能なオブジェクトのサブフィールドを FieldMask に追加します。これはフィールドマスクをゼロから作成します。

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

この場合、all_set_fields_of() メソッドと field_mask() メソッドを使って、 FieldMasks ユーティリティは目的の目標を達成できません。

次の例では、次のフィールドを含むフィールドマスクを生成します。 maximize_conversions。Google Ads API では許可されていないため誤ってフィールドがクリアされないようにして、 FieldMaskError.FIELD_HAS_SUBFIELDS エラーが発生します。

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V17::Resources::MaximizeConversions->new()
    });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask will include 'maximize_conversions',
# which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty object fields cannot
# be included in a field mask.
my $response = $api_client->CampaignService()->mutate({
    customerId => $customer_id,
    operations => [$campaign_operation]
  });

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

# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    )
  });

# 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.
# 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
my $field_mask = all_set_fields_of($campaign);
push @{$field_mask->{paths}}, "maximize_conversions.target_cpa_micros";

# Creates an operation to update the campaign with the specified fields.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => $field_mask
  });

フィールドをクリアする

次に示すように、フィールドをフィールドマスクに追加することで、フィールドを明示的にクリアできます。このフィールドを空または未定義の値に設定することもできます。たとえば「MaximizeConversions」入札戦略を使用しているキャンペーンがあると仮定また、target_cpa_micros フィールドが 0。

# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
  Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V17::Resources::MaximizeConversions->new({
      targetCpaMicros => 0
    })
  });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask, which will include 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

ネストされたサブフィールドを含むフィールドは、「オブジェクトフィールド」で示すように、定義されたサブフィールドがあります。

フィールド マスク