フィールド マスク

Google Ads API では、フィールド マスクを使用して更新を行います。フィールド マスクには、更新によって変更するすべてのフィールドが一覧表示されます。フィールド マスクに含まれていない指定フィールドは、サーバーに送信されても無視されます。

FieldMasks ユーティリティ

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

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

use Google::Ads::GoogleAds::Utils::FieldMasks qw(all_set_fields_of field_mask);

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

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

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

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

FieldMasks::all_set_fields_of() は、 FieldMasks::field_mask() の便利なメソッドです。渡されたオブジェクトを同じクラスの空のオブジェクトと比較します。上記のコードでは、次のコードも使用できます。

field_mask(
  Google::Ads::GoogleAds::V26::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 などのサブフィールドを含む target_cpa_microsなど）を含めることができます。また、サブフィールドを含めないこともできます（ ManualCpm など）。

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

Perl のオブジェクト フィールドは、gRPC で実行されるクライアント ライブラリの protobuf MESSAGE に相当します。サブフィールドが定義されていないオブジェクト フィールドを更新する場合は、前のセクションで説明したように、FieldMasks ユーティリティを使用してフィールド マスクを生成します。

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

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

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

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

次の例では、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::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V26::Resources::MaximizeConversions
      ->new(),
  });

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

# Sends the operation in a mutate request that results 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::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
  });

# Creates a field mask from the existing campaign and adds the mutable subfield
# 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 sets 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.
#
# See the guide on assigning standard and portfolio bidding strategies
# (/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::V26::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::V26::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V26::Resources::MaximizeConversions
      ->new({
        targetCpaMicros => 0,
      }),
  });

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

ネストされたサブフィールドを持つフィールドは、サブフィールドが定義されているオブジェクト フィールドで説明したように、個々のサブフィールドをクリアすることによってのみクリアできます。