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

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 के साथ पूरा नहीं होता है). रिटेल परफ़ॉर्मेंस मैक्स कैंपेन (Merchant Center फ़ीड के साथ) को एक ही ऐटॉमिक सब-बैच में ब्रैंड CampaignAsset के संसाधनों को लिंक किए बिना बनाया जा सकता है.

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)
  
  size_in_bytes = type(request).pb(request).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 फ़ील्ड में बताया जाता है कि किस सीमा का उल्लंघन हुआ है.