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

フィールドマスク

Google Ads API では、更新はフィールドマスクを使用して行われます。フィールドマスクには、更新で変更するすべてのフィールドがリストされます。フィールドマスクに含まれていない指定されたフィールドは、サーバーに送信された場合でも無視されます。

FieldMasks ユーティリティ

フィールドマスクを生成するには、組み込みのフィールドマスクユーティリティ（FieldMasks）を使用することをおすすめします。これにより、オブジェクトをゼロから作成するのではなく、変更されたオブジェクトからフィールドマスクを生成できます。

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

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

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

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

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

FieldMasks::all_set_fields_of() は、FieldMasks::field_mask() のコンビニエンスメソッドです。渡されたオブジェクトと、同じクラスの空のオブジェクトを比較します。上記のコードでは

field_mask(Google::Ads::GoogleAds::V16::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"]
  });

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

オブジェクトフィールドには、サブフィールドを含めることも（target_cpa_micros、cpc_bid_ceiling_micros、cpc_bid_floor_micros の 3 つがある MaximizeConversions など）、何も持たないこともできます（例: ManualCpm）。

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

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

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

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

一般的な例としては、新しい入札戦略のフィールドを設定せずにキャンペーンの入札戦略を更新する場合があります。以下の例は、入札戦略のサブフィールドを設定せずに、MaximizeConversions 入札戦略を使用するようにキャンペーンを更新する方法を示しています。

この場合、FieldMasks ユーティリティの all_set_fields_of() メソッドと field_mask() メソッドを使用しても、目的は達成されません。

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

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V16::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V16::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::V16::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::V16::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V16::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::V16::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::V16::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V16::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::V16::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

ネストされたサブフィールドを含むフィールドをクリアするには、個々のサブフィールドをクリアする必要があります。詳細については、サブフィールドを定義しているオブジェクトフィールドをご覧ください。

フィールド マスク