フィールド マスクを使用した更新

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

FieldMaskUtil

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

キャンペーンを更新するためのフィールド マスクの生成方法は次のとおりです。

campaign = client.resource.campaign
campaign.resource_name = client.path.campaign(customer_id, campaign_id)

mask = client.field_mask.with campaign do
  campaign.status = :PAUSED
  campaign.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

このコードでは、まず空の Campaign オブジェクトを作成し、そのリソース名を 更新するキャンペーンについて API に通知します。

この例では、まずキャンペーンで client.field_mask.with メソッドを使用します。 更新を含むブロックですこのブロックの最後に、ユーティリティの ブロック後のキャンペーンの現在のステータスを、 ブロック前のキャンペーンのステータスを確認し、 変更されたフィールドを列挙するマスク。そのフィールド マスクを 次のように変更の呼び出しに生成します。

operation = client.operation.campaign
operation.update = campaign
operation.update_mask = mask

この方法は、複雑なオペレーションを作成し、 各ステップをきめ細かく制御したいと 考えていますただし、ほとんどの場合は シンプルな Ruby ライブラリ ユーティリティを使用します。

operation = client.operation.update_resource.campaign do |c|
  c.status = :PAUSED
  c.network_settings = client.resource.network_settings do |ns|
    ns.target_search_network = false
  end
end

このメソッドは、新しい空のキャンペーン リソースを自動的に作成し、 ブロック内で行った変更に基づいてフィールド マスクが実行され、 update と update_mask を含む最終演算を返します。 値がすでに入力されています。また、キャンペーンを campaign メソッドに渡して、 キャンペーンの開始状態も指定できますこのパターンは サポートしているリソースが含まれます

手動でマスクを作成する

ライブラリ ユーティリティを使用せずにフィールド マスクをゼロから作成するには、次の操作を行います。 まず Google::Protobuf::FieldMask を作成してから、配列を作成します。 変更するすべてのフィールドの名前が入力され、 配列をフィールド マスクの path フィールドに代入します。

mask = Google::Protobuf::FieldMask.new
mask.path = ["status", "name"]

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

MESSAGE フィールドにはサブフィールド（ MaximizeConversions には、次の 3 つがあります。 target_cpa_micros、cpc_bid_ceiling_micros、cpc_bid_floor_micros）または 指定することはできません（例: ManualCpm）。

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

サブフィールドで定義されていない MESSAGE フィールドを更新する場合は、 FieldMaskUtil: 前述のフィールド マスクを生成します。

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

サブフィールドで定義されている MESSAGE フィールドを更新する場合 明示的に設定する必要がある場合は、そのメッセージに 変更可能な各 MESSAGE サブフィールドを FieldMask にマッピングします。 フィールド マスクをゼロから作成した例です。

一般的な例は、キャンペーンの入札戦略を、 新しい入札戦略のどのフィールドも 編集できるようになります次の例をご覧ください。 キャンペーンを更新して MaximizeConversions 入札戦略 入札戦略でサブフィールドを設定せずに

この例では、FieldMaskUtil の組み込みの比較を使用すると、 達成するのに役立ちます

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

# Creates a campaign with the proper resource name.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# Update the maximize conversions field within the update block, so it's
# captured in the field mask
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions
end

# 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.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

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

# Create the operation directly from the campaign's resource name. Don't do
# anything in the block so that the field mask is empty. You could modify other
# fields in this block, just not the message field that is intended to have a
# blank subfield. We'll add that below.
campaign_resource_name = client.path.campaign(customer_id, campaign_id)
operation = client.operation.update_resource.campaign(campaign_resource_name) {}

# Manually add the maximize conversions subfield to the field mask so the API
# knows to clear it.
operation.update_mask.paths << "maximize_conversions.target_cpa_micros"

# This operation succeeds.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
)

フィールドをクリアする

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

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

# Create a campaign object representing the campaign you want to change.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
end

# The field mask in this operation will include 'maximize_conversions',
# but not 'maximize_conversions.target_cpa_micros', so it will result in an
# error.
operation = client.operation.update_resource.campaign(campaign) do |c|
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Operation will fail since field mask is incorrect.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

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

# Create a campaign including the maximize conversions fields right away, since
# we're going to manually add them to the field mask.
campaign = client.resource.campaign do |c|
  c.resource_name = client.path.campaign(customer_id, campaign_id)
  c.maximize_conversions = client.resource.maximize_conversions do |mc|
    mc.target_cpa_micros = 0
  end
end

# Create the operation with an empty field mask. You may add a block here with
# other changes that will automatically get added to the field mask.
operation = client.operation.update_resource.campaign(campaign) {}

# Add the field to the field mask so the API knows to clear it.
operation.update_mask.paths << 'maximize_conversions.target_cpa_micros'

# Operation will succeed since we specified the correct field mask.
response = client.service.campaign.mutate_campaigns(
  customer_id: customer_id,
  operations: [operation],
end

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