सबसे सही तरीके और सीमाएं

BatchJobService का इस्तेमाल करते समय, इन दिशा-निर्देशों का ध्यान रखें.

थ्रूपुट को बेहतर बनाना

• कई छोटे-छोटे कामों के बजाय, कुछ बड़े कामों को प्राथमिकता दी जाती है.

• अपलोड किए गए ऑपरेशन को उनके टाइप के हिसाब से क्रम में लगाएं. हालांकि, एक-दूसरे पर निर्भर ऑपरेशन को ऐटॉमिक सब-बैच में लगातार ग्रुप किया जाना चाहिए. उदाहरण के लिए, अगर आपके जॉब में स्टैंडर्ड कैंपेन, विज्ञापन ग्रुप, और विज्ञापन ग्रुप की शर्तों को जोड़ने के ऑपरेशन शामिल हैं, तो अपलोड में ऑपरेशन को इस तरह से क्रम में लगाएं कि सभी कैंपेन ऑपरेशन पहले हों. इसके बाद, सभी विज्ञापन ग्रुप ऑपरेशन और आखिर में सभी विज्ञापन ग्रुप की शर्तों के ऑपरेशन हों.

• एक ही तरह के ऑपरेशन के लिए, उन्हें पैरंट रिसॉर्स के हिसाब से ग्रुप करने से परफ़ॉर्मेंस बेहतर हो सकती है. उदाहरण के लिए, अगर आपके पास AdGroupCriterionOperation ऑब्जेक्ट की सीरीज़ है, तो विज्ञापन ग्रुप के हिसाब से कार्रवाइयों को ग्रुप करना ज़्यादा असरदार होता है. ऐसा करने से, अलग-अलग विज्ञापन ग्रुप में विज्ञापन ग्रुप की शर्तों पर असर डालने वाली कार्रवाइयों को आपस में मिलाने से बचा जा सकता है.

बैच को अलग-अलग हिस्सों में बांटने की प्रोसेस में एटॉमिसिटी

Google Ads API, सबमिट किए गए बैच जॉब में मौजूद कार्रवाइयों को प्रोसेस करने के लिए, छोटे-छोटे सब-बैच में बांटता है. स्टैंडर्ड सब-बैच, कुछ हद तक गड़बड़ी होने पर भी लागू होते हैं. हालांकि, एक-दूसरे पर निर्भर कुछ कार्रवाइयों के सब-बैच, एक ही लेन-देन के तौर पर प्रोसेस किए जाते हैं:

• LISTING_GROUP की शर्तों (AdGroupCriterion.listing_group) के लिए, एक के बाद एक AdGroupCriterionOperation कार्रवाइयां (create, update, और remove) की जाती हैं. ये कार्रवाइयां, एक ही AdGroup को टारगेट करती हैं. अगर ग्रुप में कोई भी कार्रवाई पूरी नहीं होती है, तो CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION गड़बड़ी का मैसेज दिखता है.
• एक ही AssetGroup को टारगेट करने वाले लगातार AssetGroupListingGroupFilterOperation ऑपरेशन (create, update, और remove) (ग्रुप में कोई भी ऑपरेशन पूरा न होने पर, BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE के साथ पूरा नहीं होता).
• एक AssetGroupOperation (create) के बाद, एक ही AssetGroup को टारगेट करने वाले ज़्यादा से ज़्यादा 999 AssetGroupAssetOperation (create) ऑपरेशन (अगर ग्रुप में कोई भी ऑपरेशन पूरा नहीं होता है, तो BatchJobError.ASSET_GROUP_AND_ASSET_GROUP_ASSET_TRANSACTION_FAILURE के साथ पूरा नहीं होता है). हर AssetGroupOperation (update या remove) अपने स्टैंडअलोन सिंगल-ऑपरेशन सब-बैच में एग्ज़ीक्यूट होता है.
• ब्रैंड से जुड़े दिशा-निर्देशों की सुविधा चालू होने पर, परफ़ॉर्मेंस मैक्स कैंपेन CampaignOperation (create) (brand_guidelines_enabled को true पर सेट किया गया हो या सेट न किया गया हो, क्योंकि यह तब तक डिफ़ॉल्ट रूप से true पर सेट रहता है, जब तक कि इसे साफ़ तौर पर false पर सेट न किया जाए या यात्रा के लक्ष्यों के लिए परफ़ॉर्मेंस मैक्स कैंपेन न बनाया जाए) के बाद, एक ही Campaign को टारगेट करने वाले ज़्यादा से ज़्यादा 999 CampaignAssetOperation (create) ऑपरेशन (अगर ग्रुप में कोई भी ऑपरेशन पूरा नहीं होता है, तो BatchJobError.CAMPAIGN_AND_CAMPAIGN_ASSET_TRANSACTION_FAILURE के साथ पूरा नहीं होता है). Local Services के परफ़ॉर्मेंस मैक्स कैंपेन में, ब्रैंड से जुड़े दिशा-निर्देशों का इस्तेमाल नहीं किया जा सकता. साथ ही, इनमें ब्रैंड के CampaignAsset संसाधन शामिल नहीं किए जा सकते. कैंपेन बनाते समय, brand_guidelines_enabled को false पर सेट करें. Merchant Center फ़ीड वाले रीटेल परफ़ॉर्मेंस मैक्स कैंपेन, एक ही सब-बैच में ब्रैंड CampaignAsset संसाधनों को सिर्फ़ तब हटा सकते हैं, जब कस्टम AssetGroupAsset संसाधनों (एचटीएमएल5 MEDIA_BUNDLE ऐसेट के अलावा) के बिना कोई ऐसेटलेस कैंपेन बनाया जाता है या जब brand_guidelines_enabled को false पर सेट किया जाता है.

AssetGroup और परफ़ॉर्मेंस मैक्स कैंपेन, दोनों के लिए Campaign सब-बैच बनाना (हर सब-बैच में ज़्यादा से ज़्यादा 1,000 ऑपरेशन; 999 से ज़्यादा चाइल्ड create ऑपरेशन, अगले नॉन-ऐटॉमिक सब-बैच में चले जाते हैं):

• पैरंट create ऑपरेशन (AssetGroup या Campaign पर resource_name) और उसके बाद के चाइल्ड create ऑपरेशन (AssetGroupAsset पर asset_group या CampaignAsset पर campaign) के लिए, एक ही नेगेटिव अस्थायी आईडी तय करना ज़रूरी है.
• नए Asset संसाधनों के लिए, ज़रूरी AssetOperation (create) कार्रवाइयों को पैरंट AssetGroupOperation या CampaignOperation (create) से पहले रखें. इन्हें पैरंट create और इसके चाइल्ड लिंक create कार्रवाइयों के बीच कभी न रखें. ऐसा करने पर, ऐटॉमिक सब-बैच तुरंत बंद हो जाएगा और पैरंट संसाधन बनाने की प्रोसेस, उससे जुड़ी ऐसेट से अलग हो जाएगी.

जब कोई ऐटॉमिक सब-बैच फ़ेल हो जाता है, तो गड़बड़ी वाले ऑपरेशन के BatchJobResult.status में, पुष्टि करने से जुड़ी गड़बड़ी की जानकारी होती है. वहीं, उस सब-बैच के बाकी ऑपरेशन, उस सब-बैच के लिए लेन-देन से जुड़ी गड़बड़ी के साथ वापस ले लिए जाते हैं. गड़बड़ी की असल वजह का पता लगाने के लिए, एक ही AdGroup, AssetGroup या Campaign आईडी शेयर करने वाली आस-पास की BatchJobResult एंट्री की जांच करें.

अगर इनमें से किसी भी ग्रुप में, मिलते-जुलते ऑपरेशन को एक के बाद एक नहीं जोड़ा जाता है, तो Google Ads API उन्हें अलग-अलग सब-बैच में बांट देता है. इस वजह से, बदलाव करने पर ऐसेट की ज़रूरी शर्तें पूरी नहीं हो पाती हैं या लिस्टिंग ग्रुप ट्री अधूरे रह जाते हैं. ज़्यादा जानकारी के लिए, बैच जॉब में लिस्टिंग ग्रुप फ़िल्टर का इस्तेमाल करना और परफ़ॉर्मेंस मैक्स कैंपेन की बैच प्रोसेसिंग देखें.

लॉजिकल ग्रुपिंग

प्रॉडक्ट टारगेटिंग की हैरारकी (परफ़ॉर्मेंस मैक्स कैंपेन में AssetGroupListingGroupFilterOperation या शॉपिंग कैंपेन में AdGroupCriterionOperation) में बदलाव करने या नया AssetGroup या परफ़ॉर्मेंस मैक्स Campaign बनाने पर, एक ही पैरंट रिसॉर्स (AssetGroup, AdGroup या Campaign) को टारगेट करने वाले सभी ऑपरेशन को एक के बाद एक ग्रुप करें. इससे बैकएंड लॉक कॉन्टेंशन कम होता है और एक-दूसरे पर निर्भर ट्री एक साथ रहते हैं.

डेटा की एकरूपता

लिस्टिंग ग्रुप के फ़िल्टर ट्री और परफ़ॉर्मेंस मैक्स कैंपेन की ऐसेट से जुड़ी ज़रूरी शर्तों की पुष्टि, हर सब-बैच ट्रांज़ैक्शन के आखिर में की जाती है. इसलिए, किसी जॉब में अलग-अलग रेंज या एक साथ चल रहे जॉब में, एक ही पैरंट रिसॉर्स के अपडेट को अलग-अलग न करें.

एक साथ कई अनुरोधों को प्रोसेस करने से जुड़ी समस्याओं से बचना

• एक ही खाते के लिए एक साथ कई जॉब सबमिट करने पर, एक ही समय पर एक ही ऑब्जेक्ट पर काम करने वाले जॉब की संभावना कम करें. साथ ही, जॉब के साइज़ को बड़ा रखें. RUNNING स्टेटस वाले कई अधूरे जॉब, ऑब्जेक्ट के एक ही सेट को बदलने की कोशिश करते हैं. इससे डेडलॉक जैसी स्थितियां पैदा हो सकती हैं. इसकी वजह से, सिस्टम की स्पीड बहुत कम हो सकती है और जॉब भी फ़ेल हो सकते हैं.

• एक ही जॉब में, एक ही ऑब्जेक्ट में बदलाव करने वाले कई ऑपरेशन सबमिट न करें. ऐसा करने से, नतीजे का अनुमान नहीं लगाया जा सकता.

नतीजों को बेहतर तरीके से फ़ेच करना

• जॉब के स्टेटस को बार-बार पोल न करें. ऐसा करने पर, अनुरोध संख्या सीमित करने से जुड़ी गड़बड़ियां हो सकती हैं.

• ListBatchJobResults को कॉल करते समय, page_size को सेट न करें या इसे ज़्यादा से ज़्यादा 1000 पर सेट करें. इससे, पेज पर नंबर डालने की दोतरफ़ा यात्रा को कम किया जा सकता है. साथ ही, response_content_type को MUTABLE_RESOURCE पर सिर्फ़ तब सेट करें, जब आपका ऐप्लिकेशन resource_name से ज़्यादा, वापस किए गए रिसॉर्स फ़ील्ड की जांच करता हो.

• नतीजों का क्रम, अपलोड करने के क्रम जैसा ही होता है.

इस्तेमाल से जुड़े अन्य दिशा-निर्देश

• आपके पास यह सेट करने का विकल्प होता है कि बैच जॉब को रद्द किए जाने से पहले, उसे ज़्यादा से ज़्यादा कितनी देर तक चलाया जा सकता है. कोई नया बैच जॉब बनाते समय, metadata.execution_limit_seconds फ़ील्ड को अपनी पसंद की समयसीमा के लिए, पॉज़िटिव इंटीजर पर सेट करें. यह समयसीमा सेकंड में होनी चाहिए. अगर metadata.execution_limit_seconds को सेट नहीं किया जाता है, तो डिफ़ॉल्ट रूप से कोई समयसीमा तय नहीं होती.

• हालांकि, प्रोटोकॉल के मुताबिक हर अनुरोध में 10,000 कार्रवाइयां की जा सकती हैं, लेकिन हमारा सुझाव है कि हर AddBatchJobOperationsRequest में 1,000 से ज़्यादा कार्रवाइयां न जोड़ें. साथ ही, बाकी कार्रवाइयों को उसी जॉब में अपलोड करने के लिए, sequence_token का इस्तेमाल करें. ऑपरेशन के साइज़ के आधार पर, एक ही AddBatchJobOperationsRequest में बहुत ज़्यादा ऑपरेशन भेजने से, BatchJobError.REQUEST_TOO_LARGE गड़बड़ी हो सकती है. इस गड़बड़ी को ठीक करने के लिए, कार्रवाइयों की संख्या कम करें और AddBatchJobOperationsRequest को फिर से आज़माएं.

सीमाएं

• हर BatchJob में ज़्यादा से ज़्यादा 10 लाख कार्रवाइयां की जा सकती हैं. AddBatchJobOperations को कॉल करते समय इस सीमा को पार करने पर, ResourceCountLimitExceededError.RESOURCE_LIMIT गड़बड़ी (ErrorDetails.resource_count_details में ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB के साथ) दिखती है.

• हर खाते में एक समय पर, ज़्यादा से ज़्यादा 100 ऐक्टिव या मंज़ूरी के लिए बाकी जॉब हो सकते हैं. MutateBatchJob का इस्तेमाल करके बैच जॉब बनाते समय, इस सीमा को पार करने पर ResourceCountLimitExceededError.RESOURCE_LIMIT गड़बड़ी का मैसेज दिखता है. साथ ही, ErrorDetails.resource_count_details में ResourceLimitType.BATCH_JOBS_PER_CUSTOMER दिखता है.

• सात दिन से ज़्यादा पुरानी पेंडिंग जॉब अपने-आप हट जाती हैं.

• हर AddBatchJobOperationsRequest के लिए, हर अनुरोध में ज़्यादा से ज़्यादा 10,000 म्यूटेट ऑपरेशन किए जा सकते हैं. एक अनुरोध में 10,000 से ज़्यादा कार्रवाइयां करने पर, BatchJobError.REQUEST_TOO_LARGE गड़बड़ी का मैसेज दिखता है.

• ListBatchJobResultsRequest में page_size फ़ील्ड के लिए:

  • अगर page_size को सेट नहीं किया गया है या इसकी वैल्यू 0 है, तो यह डिफ़ॉल्ट रूप से ज़्यादा से ज़्यादा 1000 पर सेट हो जाता है.
  • अगर page_size, 1000 से ज़्यादा या 0 से कम है, तो एपीआई BatchJobError.INVALID_PAGE_SIZE गड़बड़ी दिखाता है.

• हर AddBatchJobOperationsRequest का साइज़ 4,19,37,920 बाइट से ज़्यादा नहीं होना चाहिए. इस सीमा को पार करने पर, आपको BatchJobError.REQUEST_TOO_LARGE गड़बड़ी का मैसेज मिलता है. इसके अलावा, ट्रांसपोर्ट लेयर पर अस्वीकार किए जाने पर, आपको INTERNAL_ERROR गड़बड़ी का मैसेज मिलता है. अनुरोध सबमिट करने से पहले, उसके सीरियलाइज़ किए गए साइज़ का पता लगाया जा सकता है. साथ ही, अगर साइज़ बहुत बड़ा है, तो ज़रूरी कार्रवाई की जा सकती है:

  Java

  
  static final int MAX_REQUEST_BYTES = 41_937_920;
  
  // ... (code to get the AddBatchJobOperationsRequest object)
  
  int sizeInBytes = request.getSerializedSize();
  

  C#

  
  const int MAX_REQUEST_BYTES = 41_937_920;
  
  // ... (code to get the AddBatchJobOperationsRequest object)
  
  int sizeInBytes = request.CalculateSize();
  

  PHP

  
  const MAX_REQUEST_BYTES = 41937920;
  
  // ... (code to get the AddBatchJobOperationsRequest object)
  
  $size_in_bytes = $request->byteSize();
  

  Python

  
  MAX_REQUEST_BYTES = 41_937_920
  
  # ... (code to get the AddBatchJobOperationsRequest object)
  
  # Supports both proto-plus (use_proto_plus=True) and native protobuf
  # (use_proto_plus=False) messages.
  pb = type(request).pb(request) if hasattr(type(request), "pb") else request
  size_in_bytes = pb.ByteSize()
  

  Ruby

  
  MAX_REQUEST_BYTES = 41_937_920
  
  # ... (code to get the AddBatchJobOperationsRequest object)
  
  size_in_bytes = request.to_proto.bytesize
  

  Perl

  
  use JSON::XS;
  use constant MAX_REQUEST_BYTES => 41937920;
  
  # ... (code to get the AddBatchJobOperationsRequest object)
  
  # The Perl client library uses REST/JSON; UTF-8 JSON byte length provides a
  # conservative upper-bound estimate of the serialized request size.
  my $json_encoder = JSON::XS->new->utf8->convert_blessed;
  my $size_in_bytes = length($json_encoder->encode($request));
  

बदलाव करने की एक कार्रवाई का साइज़

अनुरोध का कुल साइज़ 4,19,37,920 बाइट तक हो सकता है. हालांकि, बैच में मौजूद किसी एक MutateOperation का सीरियलाइज़ किया गया साइज़, 1,04,84,504 बाइट (10 एमआईबी में से 1,256 बाइट कम) तक ही हो सकता है. इस सीमा को पार करने पर, BatchJobError.REQUEST_TOO_LARGE गड़बड़ी का मैसेज दिखता है. ध्यान दें कि BatchJobError.REQUEST_TOO_LARGE के रेफ़रंस दस्तावेज़ में 1,04,84,504 बाइट की सीमा बताई गई है. हालांकि, अनुरोध की तीन सीमाओं में से किसी एक के पार होने पर, AddBatchJobOperations यही गड़बड़ी कोड दिखाता है. ये सीमाएं हैं: कुल अनुरोध 4,19,37,920 बाइट, एक कार्रवाई 1,04,84,504 बाइट या हर कॉल में 10,000 कार्रवाइयां. गड़बड़ी के message फ़ील्ड में बताया जाता है कि किस सीमा का उल्लंघन हुआ है.