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

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

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

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

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

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

बैच को बांटने की प्रोसेस में ऐटॉमिसिटी

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

• AdGroupCriterionOperation कार्रवाइयां एक साथ की जाती हैं (create, update, और remove). ये कार्रवाइयां LISTING_GROUP शर्तों (AdGroupCriterion.listing_group) के लिए की जाती हैं. इन कार्रवाइयों का टारगेट एक ही AdGroup होता है. अगर ग्रुप में कोई भी कार्रवाई पूरी नहीं होती है, तो CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION गड़बड़ी का मैसेज दिखता है.
• एक के बाद एक AssetGroupListingGroupFilterOperation ऑपरेशन (create, update, और remove) एक ही AssetGroup को टारगेट करते हैं (अगर ग्रुप में कोई भी ऑपरेशन पूरा नहीं होता है, तो 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 ऑपरेशन (resource_name on AssetGroup या Campaign) और उसके बाद होने वाले चाइल्ड create ऑपरेशन (asset_group on AssetGroupAsset या campaign on CampaignAsset) में, एक ही नेगेटिव अस्थायी आईडी होना चाहिए.
• नए Asset संसाधनों के लिए, ज़रूरी AssetOperation (create) कार्रवाइयों को पैरंट AssetGroupOperation या CampaignOperation (create) से पहले रखें. इन्हें पैरंट create और उसके चाइल्ड लिंक create कार्रवाइयों के बीच कभी न रखें. ऐसा करने पर, एटॉमिक सब-बैच तुरंत बंद हो जाएगा और पैरंट संसाधन बनाने की प्रोसेस, उसकी लिंक की गई ऐसेट से अलग हो जाएगी.

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

अगर इनमें से किसी भी ग्रुप में, एक के बाद एक मिलती-जुलती कार्रवाइयां नहीं जोड़ी जाती हैं, तो 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 का साइज़ 41,937,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 MiB माइनस 1,256 बाइट) है. इस सीमा से ज़्यादा अनुरोध करने पर, BatchJobError.REQUEST_TOO_LARGE गड़बड़ी का मैसेज दिखता है. ध्यान दें कि BatchJobError.REQUEST_TOO_LARGE के रेफ़रंस दस्तावेज़ में, 1,04,84,504 बाइट की सीमा बताई गई है. हालांकि, अनुरोध से जुड़ी तीन सीमाओं (अनुरोध के लिए कुल 4,19,37,920 बाइट, एक कार्रवाई के लिए 1,04,84,504 बाइट या हर कॉल के लिए 10,000 कार्रवाइयां) में से किसी भी सीमा के पार होने पर, AddBatchJobOperations यही गड़बड़ी कोड दिखाता है. साथ ही, गड़बड़ी के message फ़ील्ड में यह बताया जाता है कि किस सीमा का उल्लंघन हुआ है.