バッチジョブでリスティング グループ フィルタを使用する

AdGroupCriterion.listing_group または AssetGroupListingGroupFilter のコンテキストでリスティング グループ フィルタを使用する場合は、統合を設計する際に次の点を考慮してください。

バッチ分割

重要なポイント: 同じ AssetGroup をターゲットとする AssetGroupListingGroupFilterOperation オペレーション（create、update、remove）と、同じ AdGroup をターゲットとする LISTING_GROUP 条件（AdGroupCriterion.listing_group）の AdGroupCriterionOperation オペレーション（create、update、remove）をバッチジョブに連続して追加することをおすすめします。これにより、バッチ分割時にオペレーションのセットがアトミックに処理されます。

バッチジョブに広告グループの条件またはアセット グループのリスティング グループ フィルタを含むオペレーションがある場合、バッチジョブのオペレーションは Google Ads API サーバーで受信されると、複数のサブバッチに分割されます。バッチジョブの標準オペレーションとは異なり、リスティング グループ フィルタ オペレーションを含む各サブバッチはアトミックに処理されます。

リスティング グループ フィルタを含むバッチジョブがサブバッチに分割される方法は、次の要因によって決まります。

1. リスティング グループのフィルタの種類
2. リスティング グループのフィルタがターゲットにしている AdGroup または AssetGroup
3. オペレーションの順序

オペレーションのグループ化方法を検討します。

• 同じ AssetGroup を対象とする連続した AssetGroupListingGroupFilterOperation オペレーション（create、update、remove）は、アトミック サブバッチにグループ化されます（部分的な失敗の動作はありません）。
• 同じ AdGroup をターゲットとする LISTING_GROUP 条件（AdGroupCriterion.listing_group）の連続する AdGroupCriterionOperation オペレーション（create、update、remove）は、アトミック サブバッチにグループ化されます（部分的な失敗動作はありません）。
• 他のすべての連続するオペレーションは、アトミックでないサブバッチにグループ化されます（部分的な失敗の動作）。

注: 同じバッチジョブで AssetGroup も作成する場合は、新しい Asset リソースの前提条件となる AssetOperation（create）オペレーションを AssetGroupOperation（create）の前に配置し、その直後に AssetGroupAssetOperation（create）オペレーション（前の原子サブバッチで一緒に実行される）を配置し、その後に連続する AssetGroupListingGroupFilterOperation オペレーション（次の原子サブバッチで実行される）を配置します。これらは 2 つの別々のサブバッチを形成するため、AssetGroupListingGroupFilterOperation サブバッチでエラーが発生すると、新しく作成された AssetGroup リソースと AssetGroupAsset リソースをロールバックせずに、商品グループ フィルタがロールバックされます。

キー用語: 連続とは、バッチジョブのオペレーションの順序を指します。同じ AdGroup または AssetGroup をターゲットとするオペレーションが、別のグループをターゲットとするオペレーションとインターリーブされている場合、それらは個別のサブバッチに分割され、単一のアトミック トランザクションとして処理されなくなります。

次の図に、このコンセプトを示します。灰色の各ボックスは、Google Ads API を使用して送信されたバッチジョブを表しています。灰色のボックス内では、個々のオペレーションが色でグループ化され、Google Ads API サーバーが作成するサブバッチを表しています。各グレーボックス内のオペレーションの順序は、オペレーションがバッチジョブに追加された順序に対応しています。

制限事項

バッチジョブのコンテキストでリスティング グループ フィルタを使用する場合は、次の制限事項が適用されます。

• 同じ AdGroup を対象とする LISTING_GROUP 条件（AdGroupCriterion.listing_group）の連続する AdGroupCriterionOperation オペレーション（create、update、remove）の単一のアトミック サブバッチの長さは、20,000 オペレーションを超えてはなりません。ただし、10,000 回を超えないようにすることをおすすめします。各 AddBatchJobOperationsRequest は 10,000 オペレーションに制限されているため、10,001 ～ 20,000 オペレーションの AdGroup サブバッチは、少なくとも 2 つの連続する AddBatchJobOperations リクエストでアップロードする必要があります。
• 同じ AssetGroup を対象とする連続した AssetGroupListingGroupFilterOperation オペレーション（create、update、remove）の単一のアトミック サブバッチは、10,000 オペレーションを超えることはできません。
• これらのオペレーション数の上限のいずれかに違反した場合（または、単一のサブバッチに対するサーバーの内部シリアル化バイトサイズの上限を超えた場合）、そのサブバッチでバッチジョブが中止されます。すでに完了した以前のサブバッチはコミットされたままになりますが、違反したサブバッチとそれ以降のサブバッチのすべてのオペレーションは InternalError.INTERNAL_ERROR で失敗します。

トラブルシューティング

バッチジョブのリスティング グループ フィルタ オペレーションは 1 つのトランザクションとして処理されるため、少数の誤ったオペレーションが原因で多くのオペレーションが失敗するシナリオが発生する可能性があります。また、BatchJob オペレーションの処理方法により、障害の根本原因がダウンストリーム障害の前または後のインデックスに表示されることがあります。

たとえば、ListBatchJobResults からのレスポンスを処理する場合:

• AdGroupCriterionOperation リスティング グループの場合、同じ AdGroup を対象とする連続したオペレーションが CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION（Product group operations are atomic within the same ad group. This operation failed because another operation targeting the same ad group ID was invalid.）で失敗することがあります。
• AssetGroupListingGroupFilterOperation オペレーションの場合、同じ AssetGroup を対象とする連続したオペレーションが BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE で失敗することがあります。

これらのエラーは、同じアトミック サブバッチ内の別のオペレーションが失敗したため、そのインデックスのオペレーションがロールバックされたことを示します。問題の根本原因を特定するには、同じ AdGroup または AssetGroup ID を共有するオペレーションについて、トランザクション エラーの operation_index の前後の各 BatchJobResult の status メッセージを反復処理します。