एपीआई से जुड़ी गड़बड़ियों को समझना

इस गाइड में बताया गया है कि Data Manager API, गड़बड़ियों को कैसे मैनेज करता है और उनके बारे में कैसे बताता है. एपीआई से जुड़ी गड़बड़ियों के स्ट्रक्चर और उनके मतलब को समझना ज़रूरी है. इससे ऐसे मज़बूत ऐप्लिकेशन बनाए जा सकते हैं जो अमान्य इनपुट से लेकर, कुछ समय के लिए सेवा उपलब्ध न होने जैसी समस्याओं को आसानी से हल कर सकते हैं.

Data Manager API, Google API के स्टैंडर्ड गड़बड़ी मॉडल का पालन करता है. यह मॉडल, gRPC स्टेटस कोड पर आधारित है. एपीआई से मिली जानकारी के हर उस जवाब में Status ऑब्जेक्ट शामिल होता है जिसकी वजह से गड़बड़ी होती है. इसमें ये चीज़ें शामिल होती हैं:

  • गड़बड़ी का कोड, संख्या में.
  • गड़बड़ी का मैसेज.
  • गड़बड़ी के बारे में ज़्यादा जानकारी. हालांकि, इसे देना ज़रूरी नहीं है.

कैननिकल गड़बड़ी के कोड

Data Manager API, gRPC और एचटीटीपी से तय किए गए कैननिकल गड़बड़ी कोड के सेट का इस्तेमाल करता है. इन कोड से, गड़बड़ी के टाइप के बारे में खास जानकारी मिलती है. समस्या की बुनियादी वजह को समझने के लिए, आपको सबसे पहले इस कोड को देखना चाहिए.

इन कोड के बारे में ज़्यादा जानने के लिए, एपीआई डिज़ाइन गाइड - गड़बड़ी के कोड देखें.

गड़बड़ी मिलने पर तुरंत रिपोर्ट करने वाला मॉडल

Data Manager API, फ़ास्ट-फ़ेल मॉडल का इस्तेमाल करता है. अगर किसी अनुरोध में स्ट्रक्चर से जुड़ी गड़बड़ियां हैं या किसी ज़रूरी फ़ील्ड की पुष्टि नहीं हो पाती है, तो पूरा अनुरोध पूरा नहीं हो पाता है. साथ ही, एपीआई उस अनुरोध में मौजूद किसी भी डेटा को प्रोसेस नहीं करता है.

आंशिक रूप से काम न करने वाले मॉडल के साथ तुलना

फ़ास्ट-फ़ेल मॉडल, कुछ अन्य Google एपीआई में मौजूद पार्शियल फ़ेलियर मॉडल से अलग होता है. जैसे, Google Ads API और Campaign Manager 360 API. कुछ हद तक गड़बड़ी वाले मॉडल में, अनुरोध तब भी पूरा हो जाता है, जब कुछ रिकॉर्ड में गड़बड़ियां हों. साथ ही, जवाब में उन रिकॉर्ड की गड़बड़ी की जानकारी शामिल होती है जो पूरे नहीं हो पाए.

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

फ़ास्ट-फ़ेल मॉडल, आपके डेटा या इंटिग्रेशन से जुड़ी समस्याओं के बारे में तुरंत सूचना देकर, इन समस्याओं से बचने में मदद करता है. इससे आपको सही कार्रवाई करने में मदद मिलती है.

validateOnly की मदद से, फ़ास्ट-फ़ेल गड़बड़ियों की जांच करना

डेटा डालने और हटाने के ज़्यादातर अनुरोधों में, validateOnly फ़ील्ड का इस्तेमाल किया जा सकता है. validateOnly को true पर सेट करने पर, Data Manager API पुष्टि करने की वही बुनियादी जांच करता है जो वह सामान्य अनुरोध के लिए करता है. हालांकि, यह किसी भी डेटा को शामिल या हटाता नहीं है.

  • अगर अनुरोध में गड़बड़ियां हैं, तो यह उसी गड़बड़ी के जवाब के साथ पूरा नहीं हो पाता जो आपको सामान्य अनुरोध से मिलता है.
  • अगर अनुरोध की पुष्टि हो जाती है, तो वह पूरा हो जाता है. जवाब में, सामान्य अनुरोध की तरह ही वैकल्पिक फ़ील्ड के लिए कोई भी fieldWarnings शामिल होता है.

validateOnly का इस्तेमाल करके:

  • अपने लाइव डेटा पर असर डाले बिना, नए या अपडेट किए गए इंटिग्रेशन की जांच करना.
  • अनुरोध को फिर से भेजने से पहले, पुष्टि करें कि गड़बड़ी ठीक हो गई है.

गड़बड़ियां ठीक करना

अनुरोध पूरा न होने पर, यह तरीका अपनाएं:

  1. गड़बड़ी का टाइप जानने के लिए, गड़बड़ी का कोड देखें.

    • gRPC का इस्तेमाल करने पर, गड़बड़ी का कोड Status के code फ़ील्ड में दिखता है. अगर क्लाइंट लाइब्रेरी का इस्तेमाल किया जाता है, तो हो सकता है कि गड़बड़ी के कोड के हिसाब से, किसी खास तरह का अपवाद दिखे. उदाहरण के लिए, अगर गड़बड़ी का कोड INVALID_ARGUMENT है, तो Java के लिए क्लाइंट लाइब्रेरी, com.google.api.gax.rpc.InvalidArgumentException दिखाती है.
    • REST का इस्तेमाल करने पर, गड़बड़ी का कोड error.status पर गड़बड़ी के रिस्पॉन्स में होता है. साथ ही, इससे जुड़ा एचटीटीपी स्टेटस error.code पर होता है.

  2. गड़बड़ी के कोड के लिए, स्टैंडर्ड जानकारी वाला पेलोड देखें. स्टैंडर्ड जानकारी वाले पेलोड, Google API से मिलने वाली गड़बड़ियों के मैसेज का सेट होते हैं. ये आपको गड़बड़ी की जानकारी, व्यवस्थित और एक जैसे तरीके से देते हैं. Data Manager API से मिलने वाली हर गड़बड़ी में, स्टैंडर्ड जानकारी वाले कई पेलोड मैसेज हो सकते हैं. Data Manager API की क्लाइंट लाइब्रेरी में, गड़बड़ी से जुड़ी जानकारी वाले स्टैंडर्ड पेलोड पाने के लिए, सहायता के तरीके मौजूद हैं.

    गड़बड़ी का कोड चाहे जो भी हो, हमारा सुझाव है कि आप ErrorInfo, RequestInfo, Help, और LocalizedMessage पेलोड की जांच करें और उन्हें लॉग करें.

    • ErrorInfo में ऐसी जानकारी होती है जो शायद अन्य पेलोड में न हो.
    • RequestInfo में अनुरोध आईडी होता है. अगर आपको सहायता टीम से संपर्क करना है, तो यह आईडी आपके काम आ सकता है.
    • Help और LocalizedMessage में लिंक और अन्य जानकारी होती है, ताकि गड़बड़ी को ठीक करने में आपकी मदद की जा सके.

    इसके अलावा, BadRequest पेलोड, INVALID_ARGUMENT गड़बड़ियों के लिए मददगार होता है. इसकी वजह यह है कि इससे यह जानकारी मिलती है कि किन फ़ील्ड की वजह से गड़बड़ी हुई.

डेटा डालने से जुड़ी चेतावनियां

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

डेटा डालने का अनुरोध पूरा होने पर, एचटीटीपी स्टेटस कोड 200 मिलता है. इसमें fieldWarnings सूची में ये चेतावनियां शामिल होती हैं. हर एंट्री, FieldWarning ऑब्जेक्ट होती है. इसमें ये फ़ील्ड होते हैं:

field

अनुरोध में फ़ील्ड की जगह, स्नेक केस पाथ सिंटैक्स में.

अगर कोई पाथ किसी सूची (repeated फ़ील्ड) में मौजूद आइटम पर ले जाता है, तो उसका इंडेक्स सूची के नाम के बाद स्क्वेयर ब्रैकेट ([...]) में दिखाया जाता है.

उदाहरण के लिए, events.events[0].cart_data.items[0].merchant_product_id से अनुरोध में मौजूद पहले इवेंट के कार्ट डेटा में मौजूद पहले आइटम से जुड़ी चेतावनी की पहचान होती है.

description

इस बारे में जानकारी कि दी गई वैल्यू की वजह से चेतावनी क्यों मिली.

reason

WarningReason की enum वैल्यू, जिससे चेतावनी के टाइप की पहचान होती है.

FieldWarning के साथ उदाहरण

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

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a",
  "fieldWarnings": [
    {
      "field": "events.events[0].cart_data.items[0].merchant_product_id",
      "description": "The merchant product ID is missing in the cart item.",
      "reason": "WARNING_REASON_CART_DATA_ITEM_MERCHANT_PRODUCT_ID_MISSING"
    }
  ]
}

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

Data Manager API के लिए, सबसे सामान्य स्टैंडर्ड जानकारी वाले पेलोड ये हैं:

BadRequest

जब INVALID_ARGUMENT (एचटीटीपी स्टेटस कोड 400) के साथ कोई अनुरोध पूरा न हो, तो BadRequest पेलोड देखें.

BadRequest मैसेज से पता चलता है कि अनुरोध में मौजूद फ़ील्ड में गलत वैल्यू थीं या किसी ज़रूरी फ़ील्ड में वैल्यू मौजूद नहीं थी. BadRequest में field_violations की सूची देखें, ताकि यह पता चल सके कि किन फ़ील्ड में गड़बड़ियां हैं. हर field_violations एंट्री में, गड़बड़ी को ठीक करने में मदद करने वाली जानकारी होती है:

field

अनुरोध में फ़ील्ड की जगह, स्नेक केस पाथ सिंटैक्स में.

अगर कोई पाथ किसी सूची (repeated फ़ील्ड) में मौजूद आइटम पर ले जाता है, तो उसका इंडेक्स सूची के नाम के बाद स्क्वेयर ब्रैकेट ([...]) में दिखाया जाता है.

उदाहरण के लिए, destinations[0].operating_account.account_id, destinations सूची में पहले आइटम के operating_account में account_id है.

description

वैल्यू की वजह से गड़बड़ी होने की जानकारी.

reason

ErrorReason enum, जैसे कि INVALID_HEX_ENCODING या INVALID_CURRENCY_CODE.

BadRequest के उदाहरण

यहां BadRequest मैसेज के साथ INVALID_ARGUMENT गड़बड़ी के लिए सैंपल रिस्पॉन्स दिया गया है. field_violations से पता चलता है कि गड़बड़ी एक accountId है, जो कोई संख्या नहीं है. field वैल्यू destinations[0].login_account.account_id से पता चलता है कि फ़ील्ड के उल्लंघन वाला accountId, destinations सूची में मौजूद पहले आइटम के login_account में है.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "destinations[0].login_account.account_id",
            "description": "String is not a valid number.",
            "reason": "INVALID_NUMBER_FORMAT"
          }
        ]
      }
    ]
  }
}

यहां BadRequest मैसेज के साथ INVALID_ARGUMENT गड़बड़ी का एक और सैंपल रिस्पॉन्स दिया गया है. इस मामले में, field_violations सूची में दो गड़बड़ियां दिखती हैं:

  1. पहले event में ऐसी वैल्यू है जो इवेंट के दूसरे यूज़र आइडेंटिफ़ायर पर हेक्स-कोड में नहीं बदली गई है.

  2. दूसरे event में ऐसी वैल्यू है जो इवेंट के तीसरे यूज़र आइडेंटिफ़ायर पर हेक्स-कोड में नहीं है.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers[1]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          },
          {
            "field": "events.events[1].user_data.user_identifiers[2]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

RequestInfo

जब भी कोई अनुरोध पूरा न हो, तो RequestInfo पेलोड देखें. RequestInfo में request_id शामिल होता है, जो आपके एपीआई अनुरोध की खास तौर पर पहचान करता है.

{
  "@type": "type.googleapis.com/google.rpc.RequestInfo",
  "requestId": "t-4490c640-dc5d-4c28-91c1-04a1cae0f49f"
}

गड़बड़ियों को लॉग करते समय या सहायता टीम से संपर्क करते समय, अनुरोध आईडी ज़रूर शामिल करें. इससे समस्याओं का पता लगाने में मदद मिलती है.

ErrorInfo

ErrorInfo मैसेज की जांच करें, ताकि ऐसी अतिरिक्त जानकारी हासिल की जा सके जो अन्य स्टैंडर्ड जानकारी वाले पेलोड में कैप्चर न की गई हो. ErrorInfo पेलोड में गड़बड़ी की जानकारी वाला metadata मैप होता है.

उदाहरण के लिए, यहां ErrorInfo के लिए PERMISSION_DENIED गड़बड़ी का मैसेज दिया गया है. यह गड़बड़ी, किसी ऐसे Google Cloud प्रोजेक्ट के क्रेडेंशियल इस्तेमाल करने की वजह से हुई है जिसमें डेटा मैनेजर एपीआई चालू नहीं है. ErrorInfo से गड़बड़ी के बारे में ज़्यादा जानकारी मिलती है. जैसे:

  • अनुरोध से जुड़ा प्रोजेक्ट, metadata.consumer के तहत.
  • सेवा का नाम, metadata.serviceTitle के तहत.
  • वह यूआरएल जहां metadata.activationUrl में जाकर, सेवा को चालू किया जा सकता है.
{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SERVICE_DISABLED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "service": "datamanager.googleapis.com",
          "containerInfo": "PROJECT_NUMBER",
          "serviceTitle": "Data Manager API",
          "activationUrl": "https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
        }
      },
      ...
    ]
  }
}

कोटा और अनुरोध संख्या सीमित करने से जुड़ी गड़बड़ियां

जब कोई अनुरोध किसी प्रोजेक्ट की सीमा से ज़्यादा होता है, तो एपीआई RESOURCE_EXHAUSTED गड़बड़ी (एचटीटीपी स्टेटस कोड 429) दिखाता है. ErrorInfo पेलोड में इस बारे में जानकारी मिलती है कि किस सीमा को पार किया गया है. यह जानकारी इसके metadata मैप में होती है:

consumer
अनुरोध से जुड़ा Google Cloud प्रोजेक्ट, projects/PROJECT_NUMBER के तौर पर फ़ॉर्मैट किया गया है.
quota_limit
कोटा की उस सीमा का नाम जिसे पार किया गया है, जैसे कि IngestionMutateRequestsPerMinutePerProject या IngestionMutateRequestsPerDayPerProject. इस वैल्यू का इस्तेमाल करके यह तय किया जा सकता है कि ऐप्लिकेशन ने हर मिनट या रोज़ाना इस्तेमाल की समयसीमा को पार किया है या नहीं. सीमाओं के नामों की पूरी सूची देखने के लिए, प्रोजेक्ट की सीमाएं देखें.
quota_location
वह जगह जहां कोटा लागू किया गया है. Data Manager API के लिए, यह हमेशा global होता है.
quota_metric
सीमा से जुड़ी मेट्रिक, जैसे कि datamanager.googleapis.com/ingestion_mutate_requests.
service
सेवा का नाम, datamanager.googleapis.com.

यहां RESOURCE_EXHAUSTED गड़बड़ी के रिस्पॉन्स का एक उदाहरण दिया गया है. यह गड़बड़ी तब होती है, जब डेटा डालने के लिए किए गए बदलाव के अनुरोध, हर मिनट की तय सीमा से ज़्यादा हो जाते हैं:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric 'Ingestion mutate requests' and limit 'Ingestion mutate requests per minute' of service 'datamanager.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RATE_LIMIT_EXCEEDED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "quota_limit": "IngestionMutateRequestsPerMinutePerProject",
          "quota_location": "global",
          "quota_metric": "datamanager.googleapis.com/ingestion_mutate_requests",
          "service": "datamanager.googleapis.com"
        }
      }
    ]
  }
}

Help और LocalizedMessage

Help और LocalizedMessage पेलोड देखें. इनसे आपको दस्तावेज़ों के लिंक और स्थानीय भाषा में गड़बड़ी के मैसेज मिलेंगे. इनसे आपको गड़बड़ी को समझने और उसे ठीक करने में मदद मिलेगी.

उदाहरण के लिए, यहां PERMISSION_DENIED की गड़बड़ी के लिए Help और LocalizedMessage दिया गया है. यह गड़बड़ी, Google Cloud प्रोजेक्ट के लिए क्रेडेंशियल इस्तेमाल करने की वजह से हुई है. इस प्रोजेक्ट में, Data Manager API चालू नहीं है. Help पेलोड में वह यूआरएल दिखता है जहां सेवा को चालू किया जा सकता है. साथ ही, LocalizedMessage में गड़बड़ी की जानकारी होती है.

{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry."
      },
      {
        "@type": "type.googleapis.com/google.rpc.Help",
        "links": [
          {
            "description": "Google API Console API activation",
            "url": "https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
          }
        ]
      },
      ...
    ]
  }
}

ऐक्सेस करने में हुई गड़बड़ी की जानकारी

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

.NET

try {
    // Send API request
}
catch (Grpc.Core.RpcException rpcException)
{
    Console.WriteLine($"Exception encountered: {rpcException.Message}");
    var statusDetails =
        Google.Api.Gax.Grpc.RpcExceptionExtensions.GetAllStatusDetails(
            rpcException
        );
    foreach (var detail in statusDetails)
    {
        if (detail is Google.Rpc.BadRequest)
        {
            Google.Rpc.BadRequest badRequest = (Google.Rpc.BadRequest)detail;
            foreach (
                BadRequest.Types.FieldViolation? fieldViolation in badRequest.FieldViolations
            )
            {
                // Access attributes such as fieldViolation!.Reason and fieldViolation!.Field
            }
        }
        else if (detail is Google.Rpc.RequestInfo)
        {
            Google.Rpc.RequestInfo requestInfo = (Google.Rpc.RequestInfo)detail;
            string requestId = requestInfo.RequestId;
            // Log the requestId...
        }
        else if (detail is Google.Rpc.ErrorInfo)
        {
            Google.Rpc.ErrorInfo errorInfo = (Google.Rpc.ErrorInfo)detail;
            // Log the errorInfo.Reason and errorInfo.Metadata...

            // If handling a rate limit error, check the exceeded quota limit:
            if (errorInfo.Reason == "RATE_LIMIT_EXCEEDED" &&
                errorInfo.Metadata.TryGetValue("quota_limit", out string quotaLimit))
            {
                // Inspect quotaLimit to determine whether it is a per-minute
                // or daily limit (for example,
                // IngestionMutateRequestsPerMinutePerProject).
            }

            // Log the details in the 'Metadata' map...
            foreach (
                KeyValuePair<String, String> metadataEntry in errorInfo.Metadata
            )
            {
                // Log the metadataEntry.Key and metadataEntry.Value...
            }
        }
        else
        {
            // ...
        }
    }
}

Java

try {
  // Send API request
} catch (com.google.api.gax.rpc.InvalidArgumentException invalidArgumentException) {
  // Gets the standard BadRequest payload from the exception.
  BadRequest badRequest = invalidArgumentException.getErrorDetails().getBadRequest();
  for (int i = 0; i < badRequest.getFieldViolationsCount(); i++) {
    FieldViolation fieldViolation = badRequest.getFieldViolations(i);
    // Access attributes such as fieldViolation.getField() and fieldViolation.getReason()
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = invalidArgumentException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
} catch (com.google.api.gax.rpc.ApiException apiException) {
  // Fallback exception handler for other types of ApiException.

  // Gets the standard ErrorInfo payload from the exception.
  ErrorInfo errorInfo = apiException.getErrorDetails().getErrorInfo();
  // Log the 'reason' and 'domain'...

  // If handling a rate limit error, check the exceeded quota limit:
  if (errorInfo != null && "RATE_LIMIT_EXCEEDED".equals(errorInfo.getReason())) {
    String quotaLimit = errorInfo.getMetadataMap().get("quota_limit");
    // Inspect quotaLimit to determine whether it is a per-minute
    // or daily limit (for example,
    // IngestionMutateRequestsPerMinutePerProject).
  }

  // Log the details in the 'metadata' map...
  for (Entry<String, String> metadataEntry : errorInfo.getMetadataMap().entrySet()) {
    // Log the metadataEntry key and value...
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = apiException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
  ...
}

gRPC के लिए, हेडर के साइज़ से जुड़ी गड़बड़ियां ठीक करना

जब डेटा डालने या कॉन्टेंट हटाने के अनुरोध में मौजूद कई रिकॉर्ड की पुष्टि नहीं हो पाती है, तो Data Manager API, जवाब के BadRequest पेलोड में सभी गड़बड़ियां दिखाता है.

gRPC में, सेवा गड़बड़ी की जानकारी को एचटीटीपी/2 रिस्पॉन्स हेडर (मेटाडेटा) में दिखाती है. डिफ़ॉल्ट रूप से, gRPC क्लाइंट लाइब्रेरी, इनकमिंग हेडर को ज़्यादा से ज़्यादा साइज़ (आम तौर पर 8 से 10 केबी) तक सीमित करती हैं. अगर गड़बड़ी की जानकारी इस सीमा से ज़्यादा है, तो गड़बड़ी के जवाब को पार्स करने से पहले, क्लाइंट-साइड एचटीटीपी/2 ट्रांसपोर्ट काम नहीं करता. साथ ही, इस तरह का अपवाद दिखता है:

Http2Exception: Header size exceeded max allowed size (10240)

क्लाइंट, रिस्पॉन्स हेडर को प्रोसेस नहीं कर सकता. इसलिए, वह स्ट्रीम को रद्द कर देता है. यह सर्वर-साइड लॉग में एचटीटीपी स्टेटस 499 Client Closed Request के तौर पर दिखता है. साथ ही, आपका ऐप्लिकेशन BadRequest गड़बड़ी की जानकारी को ऐक्सेस नहीं कर सकता.

इस समस्या को हल करने और गड़बड़ियों की पूरी सूची देखने के लिए, अपने gRPC क्लाइंट को कॉन्फ़िगर करें. इसके लिए, इनकमिंग मेटाडेटा के साइज़ की ज़्यादा से ज़्यादा सीमा बढ़ाएं. जैसे, 16 एमबी:

.NET

// Creates a client for the ingestion service. Increases the maximum metadata size to
// 16MB to prevent RESOURCE_EXHAUSTED errors when responses contain large error
// details.
IngestionServiceClient ingestionServiceClient = new IngestionServiceClientBuilder
{
    GrpcChannelOptions = GrpcChannelOptions.Empty.WithCustomOption(
        "grpc.max_metadata_size",
        16 * 1024 * 1024
    ),
}.Build();

Java

// Creates a client for the ingestion service. Increases the maximum metadata size to 16MB to
// prevent RESOURCE_EXHAUSTED errors when responses contain large error details.
InstantiatingGrpcChannelProvider provider =
    IngestionServiceSettings.defaultGrpcTransportProviderBuilder()
        .setMaxInboundMetadataSize(16 * 1024 * 1024)
        .build();
IngestionServiceSettings settings =
    IngestionServiceSettings.newBuilder().setTransportChannelProvider(provider).build();
try (IngestionServiceClient ingestionServiceClient = IngestionServiceClient.create(settings)) {
  // ...
}

नोड

// Creates a client for the ingestion service. Increases the maximum metadata
// size to 16MB to prevent RESOURCE_EXHAUSTED errors when responses contain
// large error details.
const client = new IngestionServiceClient({
  'grpc.max_metadata_size': 16 * 1024 * 1024,
});

PHP

// Creates a client for the ingestion service. Increases the maximum metadata size to 16MB to
// prevent RESOURCE_EXHAUSTED errors when responses contain large error details.
$client = new IngestionServiceClient([
    'transportConfig' => [
        'grpc' => [
            'stubOpts' => [
                'grpc.max_metadata_size' => 16 * 1024 * 1024,
            ],
        ],
    ],
]);

Python

# Creates a client for the ingestion service. Increases the maximum
# metadata size to 16MB to prevent RESOURCE_EXHAUSTED errors when responses
# contain large error details.
channel = datamanager_v1.services.ingestion_service.transports.IngestionServiceGrpcTransport.create_channel(
    options=[("grpc.max_metadata_size", 16 * 1024 * 1024)]
)
transport = datamanager_v1.services.ingestion_service.transports.IngestionServiceGrpcTransport(
    channel=channel
)
client: datamanager_v1.IngestionServiceClient = (
    datamanager_v1.IngestionServiceClient(transport=transport)
)

गड़बड़ी ठीक करने के सबसे सही तरीके

मज़बूत ऐप्लिकेशन बनाने के लिए, यहां दिए गए सबसे सही तरीके अपनाएं.

न्योता भेजने से पहले पुष्टि करना
कोई इंटिग्रेशन बनाते या बदलते समय, डेटा डालने से पहले, गड़बड़ियों का तुरंत पता लगाने के लिए, validateOnly को true पर सेट करके अनुरोध भेजें.
गड़बड़ी की जानकारी देखना
हमेशा स्टैंडर्ड जानकारी वाले पेलोड में से कोई एक ढूंढें, जैसे कि BadRequest. हर स्टैंडर्ड जानकारी वाले पेलोड में, गड़बड़ी की वजह समझने में मदद करने वाली जानकारी होती है.
क्लाइंट और सर्वर की गड़बड़ियों के बीच अंतर करना

यह पता लगाएं कि गड़बड़ी, आपके लागू करने के तरीके (क्लाइंट) की वजह से हुई है या एपीआई (सर्वर) की वजह से.

  • क्लाइंट की गड़बड़ियां: INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED जैसे कोड. इनके लिए, अनुरोध या आपके ऐप्लिकेशन की स्थिति/क्रेडेंशियल में बदलाव करने की ज़रूरत होती है. समस्या को हल किए बिना, अनुरोध को फिर से न भेजें.
  • सर्वर की गड़बड़ियां: UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN जैसे कोड. इससे पता चलता है कि एपीआई सेवा में कुछ समय के लिए कोई समस्या हुई है.
फिर से कोशिश करने की रणनीति लागू करना

यह तय करें कि गड़बड़ी को ठीक करने के लिए फिर से कोशिश की जा सकती है या नहीं. साथ ही, फिर से कोशिश करने की रणनीति का इस्तेमाल करें.

  • सर्वर की कुछ समय के लिए होने वाली गड़बड़ियों (जैसे, UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN, और ABORTED) और हर मिनट के हिसाब से अनुरोध संख्या सीमित करने की गड़बड़ियों (RATE_LIMIT_EXCEEDED के साथ RESOURCE_EXHAUSTED) के लिए सिर्फ़ फिर से कोशिश करें.

  • अनुरोध संख्या सीमित करने के लिए, quota_limit में ErrorInfo की जांच करें:

    • अगर सीमा हर मिनट के हिसाब से है (जैसे कि IngestionMutateRequestsPerMinutePerProject), तो अनुरोधों को रोकें और जिटर के साथ एक्स्पोनेंशियल बैकऑफ़ का इस्तेमाल करके फिर से कोशिश करें.

    • अगर सीमा रोज़ाना की है (जैसे कि IngestionMutateRequestsPerDayPerProject), तो तुरंत कोशिश न करें. पैसिफ़िक टाइम के मुताबिक आधी रात को हर दिन का कोटा रीसेट होने तक, प्रोसेसिंग को रोकें.

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

  • बैकऑफ़ में होने वाली देरी में, "जिटर" की थोड़ी सी रैंडम वैल्यू जोड़ें. इससे "थंडरिंग हर्ड" की समस्या से बचा जा सकता है. इस समस्या में, कई क्लाइंट एक साथ फिर से कोशिश करते हैं.

पूरी जानकारी लॉग करें

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

उपयोगकर्ता से सुझाव/राय पाना

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

इन दिशा-निर्देशों का पालन करके, Data Manager API से मिलने वाली गड़बड़ियों का पता लगाया जा सकता है और उन्हें ठीक किया जा सकता है. इससे ज़्यादा भरोसेमंद और उपयोगकर्ता के लिए आसान ऐप्लिकेशन बनाए जा सकते हैं.

पीछे जाएं
उपयोगकर्ता का डेटा एन्क्रिप्ट (सुरक्षित) करें
आगे बढ़ें
सबसे सही तरीके