गड़बड़ी वाले जवाबों को मैनेज करना

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

खास जानकारी

Merchant API का अनुरोध पूरा न होने पर, एपीआई एक स्टैंडर्ड एचटीटीपी स्टेटस कोड (4xx या 5xx) दिखाता है. साथ ही, गड़बड़ी के बारे में जानकारी देने वाला JSON रिस्पॉन्स बॉडी दिखाता है. Merchant API, गड़बड़ी की जानकारी के लिए AIP-193 स्टैंडर्ड का पालन करता है. इससे मशीन के पढ़ने लायक जानकारी मिलती है. इससे आपका ऐप्लिकेशन, गड़बड़ी की खास स्थितियों को प्रोग्राम के हिसाब से हैंडल कर पाता है.

ध्यान दें: गड़बड़ी के जवाब का यह स्ट्रक्चर, Merchant API में धीरे-धीरे रोल आउट किया जा रहा है. सिर्फ़ Products, Reports, और Data sources सब-एपीआई से मिली गड़बड़ियां, यहां बताए गए फ़ॉर्मैट के मुताबिक होती हैं. ऐसा हो सकता है कि अन्य सब-एपीआई से मिली गड़बड़ियां अब भी लेगसी फ़ॉर्मैट में हों और उनमें ErrorInfoमेटाडेटा शामिल न हो.

गड़बड़ी वाले जवाब का स्ट्रक्चर

गड़बड़ी का जवाब, एक JSON ऑब्जेक्ट होता है. इसमें code, message, और status जैसे स्टैंडर्ड फ़ील्ड शामिल होते हैं. खास तौर पर, इसमें एक details ऐरे भी शामिल होता है. प्रोग्राम के हिसाब से गड़बड़ियों को ठीक करने के लिए, आपको details में मौजूद किसी ऑब्जेक्ट को देखना चाहिए. इसमें @type, type.googleapis.com/google.rpc.ErrorInfo है.

यह ErrorInfo ऑब्जेक्ट, गड़बड़ी के बारे में स्ट्रक्चर्ड डेटा उपलब्ध कराता है:

• domain: गड़बड़ी का लॉजिकल ग्रुप, आम तौर पर merchantapi.googleapis.com.
• मेटाडेटा: गड़बड़ी से जुड़ी डाइनैमिक वैल्यू का मैप. इसमें ये शामिल हैं:
  • REASON: यह गड़बड़ी की सटीक जानकारी देने वाला एक खास और स्टेबल आइडेंटिफ़ायर होता है. उदाहरण के लिए, INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). यह फ़ील्ड हमेशा मौजूद रहता है. अपने ऐप्लिकेशन लॉजिक में गड़बड़ी को ठीक करने के लिए, इस फ़ील्ड का इस्तेमाल करें.
  • HELP_CENTER_LINK: इससे समस्या को ठीक करने के लिए, ज़्यादा जानकारी और निर्देश मिलते हैं. यह फ़ील्ड, सभी गड़बड़ियों के लिए मौजूद नहीं होता. हालांकि, हमारा प्लान है कि हम समय के साथ-साथ, उन गड़बड़ियों के लिए इस फ़ील्ड को उपलब्ध कराएं जिनके बारे में ज़्यादा जानकारी की ज़रूरत हो सकती है.
  • अन्य डाइनैमिक फ़ील्ड: कॉन्टेक्स्ट देने वाली अन्य कुंजियां, जैसे कि अमान्य फ़ील्ड (FIELD_LOCATION) का नाम या वह वैल्यू जिसकी वजह से गड़बड़ी हुई (FIELD_VALUE).

गड़बड़ी के जवाबों के उदाहरण

यहां दिए गए JSON में, Merchant API की गड़बड़ी का स्ट्रक्चर दिखाया गया है. इसमें संसाधन का नाम गलत तरीके से बनाया गया है.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

पुष्टि करने में हुई गड़बड़ी का एक उदाहरण यहां दिया गया है:

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

गड़बड़ी वाले फ़ील्ड की स्थिरता

गड़बड़ी ठीक करने का लॉजिक लिखते समय, यह जानना ज़रूरी है कि किन फ़ील्ड पर भरोसा किया जा सकता है और किन फ़ील्ड में बदलाव हो सकता है.

• स्थिर फ़ील्ड:

• details.metadata.REASON: गड़बड़ी का खास आइडेंटिफ़ायर. आपको अपने ऐप्लिकेशन के कंट्रोल फ़्लो लॉजिक के लिए, इस फ़ील्ड पर भरोसा करना चाहिए.

  • details.metadata कुंजियां: मेटाडेटा मैप में मौजूद कुंजियां (जैसे, FIELD_LOCATION, ACCOUNT_IDS) स्थिर हैं.
  • code: यह एचटीटीपी स्टेटस कोड का टॉप लेवल होता है. जैसे, 400, 401, 503) स्थिर है.

• बदलाव वाले फ़ील्ड:

  • message: गड़बड़ी का ऐसा मैसेज जिसे आसानी से समझा जा सकता है, वह स्थिर नहीं है. यह सिर्फ़ डेवलपर को डीबग करने के लिए है. ऐसा कोड न लिखें जो message फ़ील्ड के टेक्स्ट कॉन्टेंट को पार्स करता हो या उस पर निर्भर हो. ऐसा इसलिए, क्योंकि इस फ़ील्ड में मौजूद कॉन्टेंट में बदलाव किया जा सकता है. ऐसा, कॉन्टेंट को ज़्यादा साफ़ तौर पर दिखाने या उसमें ज़्यादा जानकारी जोड़ने के लिए किया जाता है. इसके लिए, आपको सूचना नहीं दी जाएगी.
  • details.metadata वैल्यू: कुंजियां स्थिर होती हैं, लेकिन जानकारी देने वाली कुंजियों की वैल्यू बदल सकती हैं. उदाहरण के लिए, अगर कोई HELP_CENTER_LINK कुंजी दी जाती है, तो यह जिस यूआरएल की ओर इशारा करती है उसे बिना किसी सूचना के, नए दस्तावेज़ वाले पेज पर अपडेट किया जा सकता है. हालांकि, जैसा कि पहले बताया गया है, details.metadata.REASON की वैल्यू स्थिर है.

सबसे सही तरीके

यह पक्का करने के लिए कि आपका इंटिग्रेशन, गड़बड़ियों को आसानी से ठीक कर सके, इन सबसे सही तरीकों को अपनाएं.

लॉजिक के लिए details.metadata.REASON का इस्तेमाल करें

गड़बड़ी की वजह का पता लगाने के लिए, हमेशा metadata मैप में मौजूद REASON का इस्तेमाल करें. सिर्फ़ एचटीटीपी स्टेटस कोड पर भरोसा न करें, क्योंकि कई गड़बड़ियों का स्टेटस कोड एक जैसा हो सकता है.

गड़बड़ी के मैसेज को पार्स न करें

स्टेबिलिटी सेक्शन में बताया गया है कि message फ़ील्ड का इस्तेमाल, सिर्फ़ लोगों के लिए किया जाता है. अगर आपको डाइनैमिक जानकारी चाहिए (जैसे, कौनसा फ़ील्ड अमान्य था), तो इसे metadata मैप से निकालें. इसके लिए, FIELD_LOCATION और VARIABLE_NAME जैसी स्टेबल कुंजियों का इस्तेमाल करें.

एक्स्पोनेंशियल बैकऑफ़ लागू करना

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

• quota/request_rate_too_high: इस गड़बड़ी का मतलब है कि आपने किसी खास कोटा ग्रुप के लिए, मिनट का कोटा पार कर लिया है. अनुरोध करने की फ़्रीक्वेंसी कम करें.
• internal_error: ये आम तौर पर कुछ समय के लिए होते हैं. एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करें. ध्यान दें: अगर बैकऑफ़ के साथ कई बार फिर से कोशिश करने के बाद भी internal_error की समस्या बनी रहती है, तो Merchant API की सहायता टीम से संपर्क करने का तरीका देखें.

Merchant API की सहायता टीम से संपर्क करने का तरीका

अगर आपको किसी गड़बड़ी के बारे में Merchant API की सहायता टीम से संपर्क करना है, तो अपने अनुरोध में यह जानकारी दें:

1. गड़बड़ी का सटीक जवाब
2. एपीआई के तरीके का नाम
3. अनुरोध का पेलोड
4. टाइमस्टैंप या वह समयावधि जिसके दौरान मेथड को कॉल किया गया था और गड़बड़ियां मिली थीं