フィールド マスク

Google Ads API では、フィールド マスクを使用して更新を行います。フィールド マスクには、 更新で変更するすべてのフィールドと、指定した サーバーに送信しても無視されます。マイページ フィールド マスクを手動で作成することもできます。この場合、 Google\Protobuf\FieldMask 変更するすべてのフィールドの名前が入った配列を作成する フィールド マスクのパスフィールドに割り当てます。

組み込みのフィールド マスク ユーティリティを使用して （FieldMasks）、 特定の詳細の多くが非表示になり エンティティのフィールドに対する変更をモニタリングすることで、自動的にマスクされます。

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

    $campaign = new Campaign([
        'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
        'status' => CampaignStatus::PAUSED
    ]);

    $campaignOperation = new CampaignOperation();
    $campaignOperation->setUpdate($campaign);
    $campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

このコードは、最初に Campaign オブジェクトを作成し、次に ResourceNames: 配信中のキャンペーンを API が認識できるようにする 更新しました。status も PAUSED に設定されます。

次に、コードは CampaignOperation オブジェクトを作成し、 クリックしますその後、 FieldMasks::allSetFieldsOf() を使用して、変更されたすべてのフィールドを使用してキャンペーンのフィールド マスクを作成します。最後に、 返されたマスクをキャンペーン オペレーション オブジェクトに渡します。

注: FieldMasks::allSetFieldsOf は、次の場合に便利な方法です。 FieldMasks::compare()。 渡されたオブジェクトと、同じクラスの空のオブジェクトを比較します。対象 たとえば、以前のコードでは、allSetFieldsOf() の代わりに FieldMasks::compare(new Campaign(), $campaign) を使用できました。

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

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

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

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

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

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

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

この場合、allSetFieldsOf() メソッドと compare() メソッドを使って、 FieldMasks は目的の目標を達成していません。

次のコードは、maximize_conversions を含むフィールド マスクを生成します。 ただし、Google Ads API では、 誤ってフィールドをクリアしてしまい、 FieldMaskError.FIELD_HAS_SUBFIELDS エラーが発生します。

警告: 次のコードはエラーになります。

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'maximize_conversions' => new MaximizeConversions()
]);

// 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 = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

// 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.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);

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

成功: 以下のコードでキャンペーンの入札戦略が正常に更新されます。

// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);

// 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 = FieldMasks::allSetFieldsOf($campaign);
// 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
$fieldMask->setPaths(array_merge(
    iterator_to_array($fieldMask->getPaths()->getIterator()),
    ['maximize_conversions.target_cpa_micros']
));

// Creates an operation to update the campaign with the specified fields.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);

フィールドをクリアする

一部のフィールドは明示的にクリアできます。前の例と同様に、コマンドを フィールド マスクに明示的に追加することもできます。たとえば、24 時間 365 日の 「MaximizeConversions」入札戦略を使用し、 target_cpa_micros フィールドに、0 より大きい値が設定されています。

次のコードが実行されます。ただし、maximize_conversions.target_cpa_micros はフィールド マスクには追加されないため、 target_cpa_micros フィールド:

警告: このコードではエラーは発生しませんが、target_cpa_micros （MaximizeConversions 個の入札戦略のうち）は消去されません。

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'maximize_conversions' => new MaximizeConversions(['target_cpa' => 0]),
    'status' => CampaignStatus::PAUSED
]);

// 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 = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

// 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.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);

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

成功: 次のコードは target_cpa_micros を消去します。

// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);

// 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 = FieldMasks::allSetFieldsOf($campaign);
$fieldMask->setPaths(array_merge(
    iterator_to_array($fieldMask->getPaths()->getIterator()),
    ['maximize_conversions.target_cpa_micros']
));

// Creates an operation to update the campaign with the specified field.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);

「不正解」なのは定義されたフィールドで意図したとおりに Google Ads API protocol buffers で optional として指定します。しかし、 target_cpa_micros optional フィールドでない場合、「不正解」更新されても、 入札戦略の target_cpa フィールドを消去します。

キーポイント: フィールドをクリアしたい場合は、 そのフィールドを明示的にフィールド マスクに追加します。