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

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 オペレーションを超えることはできません。
• これらのオペレーション数の上限に違反した場合（または、1 つのサブバッチのサーバーの内部シリアル化バイトサイズの上限を超えた場合）、そのサブバッチでバッチジョブが中止されます。すでに完了している以前のサブバッチは commit されたままになりますが、違反したサブバッチとそれ以降のサブバッチのすべてのオペレーションは 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 ID または AssetGroup ID を共有するオペレーションについて、トランザクション エラーの operation_index の前後で、各 BatchJobResult の status メッセージを反復処理します。