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

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 フィールドにはサブフィールドを含めることができます（target_cpa_micros、cpc_bid_ceiling_micros、cpc_bid_floor_micros の 3 つを含む MaximizeConversions など）。サブフィールドを含めないこともあります（ManualCpm など）。

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

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

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

サブフィールドで定義された MESSAGE フィールドを更新するときに、そのメッセージのサブフィールドを明示的に設定しない場合、フィールドマスクを最初から作成した前述の例と同様に、変更可能な MESSAGE サブフィールドを FieldMask に手動で追加する必要があります。

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

この例では、FieldMaskUtil の組み込み比較を使用しても、目的の目標は達成されません。

次のコードは、maximize_conversions を含むフィールドマスクを生成します。ただし、Google 広告 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],
)

フィールドの消去

一部のフィールドは明示的に消去できます。前の例と同様に、これらのフィールドをフィールドマスクに明示的に追加する必要があります。たとえば、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

次のコードは、MaximizeConversions 入札戦略の target_cpa_micros フィールドを適切に消去する方法を示しています。

# 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 広告 API の protocol buffers で optional として定義されているフィールドに対しては、想定どおりに機能します。ただし、target_cpa_micros は optional フィールドではないため、「正しくない」コードは入札戦略を更新して target_cpa フィールドを消去しません。

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