एपीआई की सीमाएं और कोटा

Google Ads API, एपीआई से जुड़ी कार्रवाइयों पर सीमाएं लागू करता है. जैसे, बदलाव के एक अनुरोध में भेजी जा सकने वाली कार्रवाइयों की संख्या. यहां दी गई टेबल में, कुछ ज़रूरी सीमाओं और कोटा के बारे में खास जानकारी दी गई है. इनके बारे में जानना ज़रूरी है.

एपीआई के रोज़ाना इस्तेमाल की सीमाएं

एपीआई के रोज़ाना इस्तेमाल की सीमाएं, आपके Google Cloud प्रोजेक्ट से किए गए एपीआई ऑपरेशन की संख्या पर आधारित होती हैं. एपीआई ऑपरेशन, Search और SearchStream अनुरोधों, अलग-अलग म्यूटेट ऑपरेशन, और सेवा के अन्य अनुरोधों का कुल योग होते हैं. एपीआई के रोज़ाना के ऑपरेशन की सीमाएं, आपके Google Cloud प्रोजेक्ट के एपीआई ऐक्सेस लेवल पर निर्भर करती हैं. ऐक्सेस लेवल और इस्तेमाल की अनुमति से जुड़ी गाइड में, हर ऐक्सेस लेवल के लिए एपीआई के इस्तेमाल की खास सीमाओं के बारे में बताया गया है.

इन सीमाओं का उल्लंघन करने वाले अनुरोधों को अस्वीकार कर दिया जाता है. साथ ही, यह गड़बड़ी दिखती है: RESOURCE_EXHAUSTED.

gRPC की सीमाएं

Google Ads API की सभी क्लाइंट लाइब्रेरी, अनुरोध और जवाब जनरेट करने के लिए gRPC का इस्तेमाल करती हैं. डिफ़ॉल्ट रूप से, gRPC में मैसेज का साइज़ 4 एमबी होता है. हालांकि, हमारी क्लाइंट लाइब्रेरी, मैसेज का साइज़ ज़्यादा से ज़्यादा 64 एमबी पर सेट करती हैं, ताकि परफ़ॉर्मेंस को बेहतर बनाया जा सके.

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

इस सीमा का उल्लंघन करने वाले अनुरोधों से GoogleAdsError जनरेट नहीं होगा. इसके बजाय, RESOURCE_EXHAUSTED (gRPC कोड 8 / एचटीटीपी 429) गड़बड़ी जनरेट होगी. gRPC गड़बड़ी के कोड और मैसेज की सूची देखें.

बदलाव के अनुरोध

उपयोगकर्ता के रोज़ के ऑपरेशन कोटा में गिने जाने के अलावा, बदलाव के अनुरोध में हर अनुरोध के लिए, 10,000 से ज़्यादा बदलाव के ऑपरेशन शामिल नहीं हो सकते. इस सीमा का उल्लंघन करने वाले अनुरोधों को अस्वीकार कर दिया जाता है. साथ ही, यह गड़बड़ी दिखती है: TOO_MANY_MUTATE_OPERATIONS.

कुछ सेवाओं और अनुरोध के टाइप के लिए, अतिरिक्त सीमाएं और ज़रूरी बातें यहां बताई गई हैं.

खोज अनुरोध

Search या SearchStream के अनुरोध को, उपयोगकर्ता के रोज़ के ऑपरेशन कोटा के हिसाब से एक ऑपरेशन माना जाता है. SearchStream के एक अनुरोध को एक एपीआई ऑपरेशन के तौर पर गिना जाता है, भले ही बैच की संख्या कितनी भी हो.

पेज के हिसाब से अनुरोध

पेज के हिसाब से किए गए अनुरोध (उदाहरण के लिए, ऐसे अनुरोध जिनमें मान्य next_page_token शामिल है) को उपयोगकर्ता के रोज़ के ऑपरेशन कोटा में नहीं गिना जाता. हालांकि, पेज नंबर वाले ऐसे अनुरोध जिनमें अमान्य या समयसीमा खत्म हो चुका पेज टोकन शामिल है, उनसे एक अपवाद जनरेट होगा. साथ ही, उन्हें हर दिन के ऑपरेशन कोटे में गिना जाएगा.

पेज नंबर डालने के बारे में ज़्यादा जानने के लिए, नतीजों के लिए पेज नंबर डालना लेख पढ़ें.

अन्य तरह के अनुरोध

ऐसा अनुरोध जो Mutate, Search या SearchStream अनुरोध नहीं है, उसे उपयोगकर्ता के रोज़ के ऑपरेशन कोटे के हिसाब से एक ऑपरेशन के तौर पर गिना जाता है.

इस तरह के अनुरोधों के कुछ उदाहरण यहां दिए गए हैं:

• BatchJobService.ListBatchJobResults
• ConversionUploadService.UploadCallConversions
• ConversionUploadService.UploadClickConversions
• OfflineUserDataJobService.AddOfflineUserDataJobOperations
• OfflineUserDataJobService.CreateOfflineUserDataJob
• UserDataService.UploadUserData

एपीआई अपवाद दिखाने वाले अनुरोध

GoogleAdsFailure के साथ अस्वीकार किए गए अनुरोधों को अब भी उपयोगकर्ता के रोज़ के ऑपरेशन कोटा में गिना जाता है.

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

कीवर्ड प्लानिंग सेवा

लागत और जटिलता की वजह से, कीवर्ड प्लानिंग सेवा के इन तरीकों पर अन्य तरह के अनुरोधों से अलग सीमाएं लागू होती हैं.

• हर सीआईडी के लिए, हर सेकंड एक अनुरोध की सीमा:

  • KeywordPlanIdeaService.GenerateKeywordIdeas
  • KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
  • KeywordPlanIdeaService.GenerateKeywordForecastMetrics

  इन सीमाओं का उल्लंघन करने वाले अनुरोधों को अस्वीकार कर दिया जाता है. साथ ही, गड़बड़ी का यह मैसेज दिखता है: RESOURCE_EXHAUSTED.

• एक क्यूपीएस का मतलब है, 60 सेकंड में 60 अनुरोध.

• हर सीआईडी के लिए, हर सेकंड दो अनुरोध किए जा सकते हैं:

  • KeywordPlanIdeaService.GenerateAdGroupThemes

कीवर्ड प्लान बनाते समय इन सीमाओं का ध्यान रखें.

ऑडियंस के बारे में अहम जानकारी देने वाली सेवा

AudienceInsightsService में मौजूद इन तरीकों पर, कोटे की कुछ सीमाएं लागू होती हैं.

• हर सीआईडी के लिए, हर दिन करीब 200 अनुरोध किए जा सकते हैं:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• हर Google Cloud प्रोजेक्ट के लिए, हर सेकंड दो अनुरोध किए जा सकते हैं:
  • AudienceInsightsService.GenerateTargetingSuggestionMetrics

कन्वर्ज़न अपलोड करने की सेवा

• हर अनुरोध के लिए, कॉल या क्लिक कन्वर्ज़न की संख्या 2,000 तक सीमित है:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

  इन सीमाओं का उल्लंघन करने वाले अनुरोधों को अस्वीकार कर दिया जाता है. साथ ही, यह गड़बड़ी दिखती है: TOO_MANY_CONVERSIONS_IN_REQUEST.

कन्वर्ज़न अडजस्टमेंट अपलोड करने की सेवा

• हर अनुरोध के लिए, कन्वर्ज़न अडजस्टमेंट की संख्या 2,000 तक सीमित है:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  इन सीमाओं का उल्लंघन करने वाले अनुरोधों को अस्वीकार कर दिया जाता है. साथ ही, यह गड़बड़ी दिखती है: TOO_MANY_ADJUSTMENTS_IN_REQUEST.

कन्वर्ज़न वैल्यू के नियम

• हर खाते के लिए, कन्वर्ज़न वैल्यू के लिए ज़्यादा से ज़्यादा 1,00,000 नियम बनाए जा सकते हैं.

  इस सीमा का उल्लंघन करने वाले अनुरोधों को अस्वीकार कर दिया जाता है. साथ ही, ResourceCountLimitExceededError.ACCOUNT_LIMIT गड़बड़ी का मैसेज दिखता है.

अगर खाते में CUSTOMER के attachment_type वाला ConversionValueRuleSet पहले से मौजूद है, तो आपको कन्वर्ज़न वैल्यू के लिए कोई भी नया नियम उस सेट में जोड़ना होगा, ताकि वे चालू हो सकें. अगर कन्वर्ज़न वैल्यू के लिए नियमों का ऐसा कोई सेट मौजूद नहीं है, तो आपको एक सेट बनाना होगा. साथ ही, उसमें कन्वर्ज़न वैल्यू के लिए नियम जोड़ने होंगे. इसके बारे में नियमों के सेट बनाएं में बताया गया है.

बिलिंग और खाते के बजट से जुड़ी सेवाएं

• म्यूटेट सिर्फ़ उन खातों के लिए किए जा सकते हैं जिन्हें महीने के इनवॉइस के लिए कॉन्फ़िगर किया गया है.

  इस सीमा का उल्लंघन करने वाले अनुरोधों को अस्वीकार कर दिया जाता है. साथ ही, यह गड़बड़ी दिखती है: MUTATE_NOT_ALLOWED.

• बदलाव के अनुरोधों के लिए, सिर्फ़ एक कार्रवाई की अनुमति है.

  इस सीमा का उल्लंघन करने वाले अनुरोधों को अस्वीकार कर दिया जाता है. साथ ही, यह गड़बड़ी दिखती है: TOO_MANY_MUTATE_OPERATIONS.

• एक ही खाते के बजट (AccountBudget या AccountBudgetProposal) में बदलाव करने के बीच, आपको कम से कम 12 घंटे इंतज़ार करना चाहिए. अगर 12 घंटे बीतने से पहले बदलाव किए जाते हैं, तो ऐसी गड़बड़ियां हो सकती हैं जिन्हें ठीक नहीं किया जा सकता. इन्हें सिर्फ़ आपके Google Ads खाते का प्रतिनिधि ही ठीक कर सकता है.

ग्राहक खातों के लिए न्योते

CustomerUserAccessInvitationService का इस्तेमाल करके, नए उपयोगकर्ताओं को मौजूदा क्लाइंट खातों में शामिल होने का न्योता भेजा जा सकता है. इस सुविधा का इस्तेमाल करके, अन्य उपयोगकर्ताओं को न्योते के ईमेल भेजे जाते हैं. इसलिए, इसका गलत इस्तेमाल किया जा सकता है. इस वजह से, इसके इस्तेमाल पर कुछ पाबंदियां लगाई गई हैं:

• उपयोगकर्ताओं को एक ही क्लाइंट खाते के लिए, एक से ज़्यादा न्योते नहीं मिल सकते. अगर किसी ऐसे उपयोगकर्ता को न्योता भेजने का अनुरोध किया जाता है जिसे पहले ही न्योता भेजा जा चुका है, तो गड़बड़ी का यह मैसेज दिखता है: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

• क्लाइंट खातों में एक बार में, 70 से ज़्यादा न्योते मंज़ूरी के लिए बाकी नहीं रह सकते. अगर कोई ऐसा अनुरोध भेजा जाता है जिससे यह वैल्यू बढ़ जाती है, तो यह गड़बड़ी दिखती है: PENDING_INVITATIONS_LIMIT_EXCEEDED.

उपयोगकर्ता का डेटा

उपयोगकर्ता के डेटा को UserDataService और OfflineUserDataJobService के हिसाब से मैनेज किया जाता है.

create या remove ऑपरेशन में मौजूद हर UserData ऑब्जेक्ट, किसी एक असली उपयोगकर्ता से जुड़ा होता है. एक UserData ऑब्जेक्ट में मौजूद user_identifiers फ़ील्ड में, ज़्यादा से ज़्यादा 20 आइडेंटिफ़ायर हो सकते हैं. किसी एक UserData ऑब्जेक्ट में इस सीमा को पार करने पर, OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS या UserDataError.TOO_MANY_USER_IDENTIFIERS गड़बड़ी का मैसेज दिखेगा.

20 से ज़्यादा आइडेंटिफ़ायर वाले उपयोगकर्ताओं को मैनेज करना

अगर किसी असली उपयोगकर्ता के पास 20 से ज़्यादा आइडेंटिफ़ायर हैं और आपको उन्हें अपलोड करना है, तो आपको इन आइडेंटिफ़ायर को कई UserData ऑब्जेक्ट में बांटना चाहिए. यह पक्का करने के लिए कि Google इन सभी आइडेंटिफ़ायर को एक ही असली उपयोगकर्ता से जोड़ सके, उस उपयोगकर्ता के हर UserData ऑब्जेक्ट में कम से कम एक सामान्य user_identifier शामिल होना चाहिए. जैसे, एक ही hashed_email, hashed_phone_number या third_party_user_id. Google, शेयर किए गए इन आइडेंटिफ़ायर का इस्तेमाल करके, अलग-अलग UserData ऑपरेशन से मिली जानकारी को असली उपयोगकर्ता की सही प्रोफ़ाइल से लिंक और मर्ज करता है.

अगर व्यक्तिगत पहचान से जुड़ी जानकारी (पीआईआई) का इस्तेमाल किया जाता है, जैसे कि हैश किए गए ईमेल या फ़ोन नंबर, तो पक्का करें कि उन्हें Google Ads API की ज़रूरी शर्तों (SHA-256, अंग्रेज़ी के छोटे अक्षर, कोई खाली जगह नहीं) के मुताबिक नॉर्मलाइज़ और हैश किया गया हो. इससे लिंक करने में आने वाली गड़बड़ियों को रोका जा सकता है.

उदाहरण के लिए, अगर किसी उपयोगकर्ता के पास 30 ईमेल पते हैं, तो दो UserData ऑब्जेक्ट भेजे जा सकते हैं, जो एक सामान्य third_party_user_id शेयर करते हैं. इसके लिए, पहले ऑब्जेक्ट में thirdPartyUserId और 1 से 19 तक के ईमेल पते डालें, ताकि 20 आइडेंटिफ़ायर की सीमा के अंदर रहा जा सके. इसके बाद, दूसरे ऑब्जेक्ट में thirdPartyUserId और 20 से 30 तक के ईमेल पते डालें:

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

एक AddOfflineUserDataJobOperationsRequest में सभी कार्रवाइयों के लिए, user_identifiers की कुल सीमा 1,00,000 है. एक OfflineUserDataJob में कई AddOfflineUserDataJobOperationsRequest कॉल किए जा सकते हैं. हालांकि, हर जॉब के लिए ज़्यादा से ज़्यादा 10,00,000 कार्रवाइयां करने का सुझाव दिया जाता है. UploadUserDataRequest (UserDataService.UploadUserData) का इस्तेमाल करके, सिंक्रोनस अपलोड के लिए हर अनुरोध में ज़्यादा से ज़्यादा 10 ऑपरेशन और पूरे अनुरोध में 100 user_identifiers शामिल किए जा सकते हैं.

अन्य तरह की सीमाएं

किसी अनुरोध में, दोहराए गए फ़ील्ड में बहुत सारे आइटम होने पर, गड़बड़ी हो सकती है. जैसे, कार्रवाइयों की सूची. REQUEST_SIZE_LIMIT_EXCEEDED. गड़बड़ी का यह मैसेज, अन्य समस्याओं की वजह से भी दिख सकता है.

अगर आपको इस सीमा का सामना करना पड़ता है और आपने ऐसे अनुरोध किए हैं जिनमें दोहराए गए फ़ील्ड का इस्तेमाल किया गया है, तो दोहराए गए फ़ील्ड में मौजूद आइटम की संख्या को कम करें. इसके लिए, कार्रवाइयों की सूची को कई बदलाव के अनुरोधों में बांटें.

GAQL क्वेरी करते समय, IN क्लॉज़ में ज़्यादा से ज़्यादा 20,000 आइटम हो सकते हैं. इस सीमा को पार करने पर, FILTER_HAS_TOO_MANY_VALUES गड़बड़ी का मैसेज दिखता है.