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