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

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

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

  • यह संख्या के तौर पर गड़बड़ी का कोड है.
  • गड़बड़ी का मैसेज.
  • गड़बड़ी के बारे में ज़्यादा जानकारी (ज़रूरी नहीं).

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

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

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

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

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

  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, QuotaFailure, और RetryInfo पेलोड, गड़बड़ी के कुछ कोड के लिए काम के होते हैं:

    • अगर स्टेटस कोड INVALID_ARGUMENT है, तो BadRequest पेलोड देखें. इससे आपको यह जानकारी मिलेगी कि किन फ़ील्ड की वजह से गड़बड़ी हुई है.
    • अगर स्टेटस कोड RESOURCE_EXHAUSTED है, तो कोटे की जानकारी और फिर से कोशिश करने में लगने वाले समय के सुझाव के लिए, QuotaFailure और RetryInfo पेलोड देखें.

स्टैंडर्ड डिटेल पेलोड

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

BadRequest

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

BadRequest मैसेज से पता चलता है कि अनुरोध में ऐसे फ़ील्ड शामिल थे जिनकी वैल्यू गलत थी या किसी ज़रूरी फ़ील्ड की वैल्यू मौजूद नहीं थी. field_violations में मौजूद field_violations सूची देखें. इससे आपको पता चलेगा कि किन फ़ील्ड में गड़बड़ियां हैं.BadRequest हर 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"
          }
        ]
      }
    ]
  }
}

यहां INVALID_ARGUMENT की गड़बड़ी का एक और सैंपल जवाब दिया गया है. इसमें BadRequest मैसेज भी शामिल है. इस मामले में, 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"
          }
        ]
      }
    ]
  }
}

QuotaFailure और RetryInfo

अनुरोध के RESOURCE_EXHAUSTED (एचटीटीपी स्टेटस कोड 429) के साथ पूरा न होने पर, QuotaFailure और RetryInfo पेलोड की जांच करें.

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

गड़बड़ी के मैसेज में RetryInfo मैसेज भी शामिल हो सकता है. इससे पता चलता है कि अनुरोध को फिर से भेजने के लिए, retry_delay का सुझाव दिया गया है.

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 प्रोजेक्ट के क्रेडेंशियल इस्तेमाल किए हैं जिसमें Data Manager API चालू नहीं है. 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.developers.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.developers.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
        }
      },
      ...
    ]
  }
}

Help और LocalizedMessage

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

उदाहरण के लिए, यहां PERMISSION_DENIED के लिए Help और LocalizedMessage दिया गया है. यह PERMISSION_DENIED, Google Cloud प्रोजेक्ट के क्रेडेंशियल इस्तेमाल करने की वजह से हुआ है. इस प्रोजेक्ट में Data Manager API चालू नहीं है. Help पेलोड में, उस यूआरएल को दिखाया जाता है जहां सेवा चालू की जा सकती है. साथ ही, 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.developers.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.developers.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 developers console API activation",
            "url": "https://console.developers.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.QuotaFailure)
        {
            Google.Rpc.QuotaFailure quotaFailure = (Google.Rpc.QuotaFailure)detail;
            foreach (
                Google.Rpc.QuotaFailure.Types.Violation violation in quotaFailure.Violations
            )
            {
                // Access attributes such as violation.Subject and violation.QuotaId
            }
        }
        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.QuotaFailureException quotaFailureException) {
  // Gets the standard QuotaFailure payload from the exception.
  QuotaFailure quotaFailure = quotaFailureException.getErrorDetails().getQuotaFailure();
  for (int i = 0; i < quotaFailure.getViolationsCount(); i++) {
    QuotaFailure.Violation violation = quotaFailure.getViolations(i);
    // Access attributes such as violation.getSubject() and violation.getQuotaId()
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = quotaFailureException.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.
  ...
}

गड़बड़ियों को ठीक करने के सबसे सही तरीके

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

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

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

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

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

  • UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN, और ABORTED जैसी कुछ समय के लिए होने वाली सर्वर की गड़बड़ियों के लिए, सिर्फ़ फिर से कोशिश करें.
  • एक्सपोनेंशियल बैकऑफ़ एल्गोरिदम का इस्तेमाल करके, फिर से कोशिश करने के बीच के समय को बढ़ाएं. इससे, पहले से ही तनाव में चल रही सेवा पर ज़्यादा दबाव नहीं पड़ता. उदाहरण के लिए, पहले एक सेकंड, फिर दो सेकंड, फिर चार सेकंड तक इंतज़ार करें. ऐसा तब तक करें, जब तक कि फिर से कोशिश करने की ज़्यादा से ज़्यादा संख्या या इंतज़ार करने का कुल समय पूरा न हो जाए.
  • बैकऑफ़ में होने वाली देरी में थोड़ा-सा रैंडम "जिटर" जोड़ें, ताकि "थंडरिंग हर्ड" की समस्या से बचा जा सके. इस समस्या में, कई क्लाइंट एक साथ फिर से कोशिश करते हैं.
पूरी जानकारी लॉग करना

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

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

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

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

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