एपीआई को कॉल करने के लिए REST का इस्तेमाल करना

इस दस्तावेज़ में Custom Search JSON API को इस्तेमाल करने के तरीके के बारे में बताया गया है.

अनुरोध करें

Custom Search JSON API में REST या Representational State Transfer, सामान्य RESTful API से कुछ अलग होता है. संसाधनों का ऐक्सेस देने के बजाय, एपीआई किसी सेवा का ऐक्सेस देता है. इस वजह से, एपीआई एक यूआरआई उपलब्ध कराता है, जो सेवा एंडपॉइंट के तौर पर काम करता है.

किसी खास खोज के नतीजे पाने के लिए, उसके यूआरआई पर एचटीटीपी GET अनुरोध भेजें. खोज के अनुरोध की जानकारी को क्वेरी पैरामीटर के तौर पर पास किया जाता है. Custom Search JSON API के यूआरआई का फ़ॉर्मैट इस तरह का होता है:

https://www.googleapis.com/customsearch/v1?[parameters]

खोज के हर अनुरोध के साथ, तीन क्वेरी [parameters] ज़रूरी हैं:

  • एपीआई पासकोड - अपने ऐप्लिकेशन की पहचान करने के लिए, key क्वेरी पैरामीटर का इस्तेमाल करें.

    • Programmable Search Engine का आईडी - cx का इस्तेमाल करके, उस Programmable Search Engine के बारे में बताएं जिसका इस्तेमाल करके आपको यह खोज करनी है. सर्च इंजन को कंट्रोल पैनल की मदद से बनाया जाना चाहिए.ध्यान दें: सर्च इंजन आईडी (cx) का फ़ॉर्मैट अलग हो सकता है. उदाहरण के लिए, 8ac1ab64606d234f1
  • सर्च क्वेरी - अपनी सर्च क्वेरी तय करने के लिए, q क्वेरी पैरामीटर का इस्तेमाल करें.

अन्य सभी क्वेरी पैरामीटर वैकल्पिक हैं.

यहां एक अनुरोध का उदाहरण दिया गया है, जो लेक्चर के लिए, टेस्ट Programmable Search Engine को खोजता है:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

क्वेरी पैरामीटर

अपने अनुरोध में दो तरह के पैरामीटर पास किए जा सकते हैं:

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

सभी पैरामीटर वैल्यू को कोड में बदलना ज़रूरी है.

एपीआई के हिसाब से क्वेरी पैरामीटर

अनुरोध के ऐसे पैरामीटर जो खास तौर पर Custom Search JSON API पर लागू होते हैं और खोज के लिए आपके अनुरोध को तय करते हैं, उनकी खास जानकारी रेफ़रंस में दी गई है.

स्टैंडर्ड क्वेरी पैरामीटर

Custom Search JSON API के सभी ऑपरेशन पर लागू होने वाले क्वेरी पैरामीटर, सिस्टम पैरामीटर में दर्ज किए जाते हैं.

जवाब का डेटा

अगर अनुरोध पूरा हो जाता है, तो सर्वर 200 OK एचटीटीपी स्टेटस कोड और JSON फ़ॉर्मैट में जवाब के डेटा के साथ जवाब देता है. रेफ़रंस में जाकर, जवाब के डेटा स्ट्रक्चर को देखा जा सकता है.

रिस्पॉन्स डेटा एक JSON ऑब्जेक्ट होता है. इसमें तीन तरह की प्रॉपर्टी शामिल होती हैं:

  • अनुरोध की गई खोज (और, शायद मिलती-जुलती खोज के अनुरोधों) के बारे में जानकारी देने वाला मेटाडेटा
  • Programmable Search Engine के बारे में जानकारी देने वाला मेटाडेटा
  • खोज के नतीजे

हर प्रॉपर्टी के बारे में ज़्यादा जानकारी के लिए, रेफ़रंस देखें.

खोज के अनुरोध का मेटाडेटा

खोज के मेटाडेटा में ये शामिल हैं:

  • url प्रॉपर्टी, जिसमें इस अनुरोध में दिखाए गए नतीजों के लिए इस्तेमाल किए गए OpenSearch टेंप्लेट के बारे में जानकारी होती है.
  • queries प्रॉपर्टी, जो ऑब्जेक्ट का एक कलेक्शन है. इसमें संभावित खोजों की विशेषताओं के बारे में बताया जाता है. अरे में मौजूद हर ऑब्जेक्ट का नाम, OpenSearch क्वेरी रोल का नाम होता है या इस एपीआई से तय किए गए दो कस्टम रोल में से कोई एक होता है: previousPage और nextPage. क्वेरी रोल ऑब्जेक्ट में ये शामिल हो सकते हैं:
    • request: नतीजों के मौजूदा सेट के लिए, क्वेरी के बारे में बताने वाला मेटाडेटा.
    • यह भूमिका, जवाब में हमेशा मौजूद होती है.
      • यह हमेशा सिर्फ़ एक एलिमेंट वाला कलेक्शन होता है.
      • nextPage: नतीजों के अगले पेज के लिए इस्तेमाल की जाने वाली क्वेरी के बारे में बताने वाला मेटाडेटा.
        • अगर मौजूदा नतीजे आखिरी पेज पर हैं, तो यह भूमिका मौजूद नहीं होती. ध्यान दें: यह एपीआई सिर्फ़ पहले 100 नतीजे दिखाता है.
        • अगर यह मौजूद है, तो यह हमेशा सिर्फ़ एक एलिमेंट वाला कलेक्शन होता है.
    • previousPage: नतीजों के पिछले पेज पर जाने के लिए, इस्तेमाल की जाने वाली क्वेरी के बारे में बताने वाला मेटाडेटा.
      • अगर मौजूदा नतीजे पहले पेज पर हैं, तो यह मौजूद नहीं होता.
      • अगर यह मौजूद है, तो यह हमेशा सिर्फ़ एक एलिमेंट वाला कलेक्शन होता है.

सर्च इंजन का मेटाडेटा

context प्रॉपर्टी में, सर्च क्वेरी को प्रोसेस करने वाले सर्च इंजन के बारे में बताने वाला मेटाडेटा होता है. इसमें सर्च इंजन का नाम और खोज को बेहतर बनाने के लिए, फ़ैसेट ऑब्जेक्ट शामिल होते हैं.

खोज के नतीजे

items कलेक्शन में, खोज के असल नतीजे शामिल होते हैं. खोज के नतीजों में यूआरएल, टाइटल, और टेक्स्ट स्निपेट शामिल होते हैं. इनसे नतीजे के बारे में जानकारी मिलती है. इसके अलावा, अगर लागू हो, तो उनमें रिच स्निपेट की जानकारी भी शामिल हो सकती है.

अगर खोज के नतीजों में promotions प्रॉपर्टी शामिल है, तो इसमें प्रमोशन का एक सेट शामिल होता है.

JavaScript से REST

JavaScript से REST का इस्तेमाल करके, Custom Search JSON API को शुरू किया जा सकता है. इसके लिए, callback क्वेरी पैरामीटर और कॉलबैक फ़ंक्शन का इस्तेमाल करें. इससे आपको ऐसे बेहतरीन ऐप्लिकेशन बनाने में मदद मिलती है जो सर्वर साइड कोड लिखे बिना, Programmable Search Engine का डेटा दिखाते हैं.

नीचे दिए गए उदाहरण में, इस तरीके का इस्तेमाल करके lecture क्वेरी के लिए, खोज के नतीजों का पहला पेज दिखाया गया है:

<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
    <div id="content"></div>
    <p id="demo"></p>
    <script>
    function hndlr(response) {
      if (response.items == null) {
        document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
      } else {
        for (var i = 1; i < response.items.length; i++) {
          var item = response.items[i];
          // Make sure HTML in item.htmlTitle is escaped.
          document.getElementById("content").append(
            document.createElement("br"),
            document.createTextNode(item.htmlTitle)
          );
        }
      }
    }
    </script>
    <script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=lecture&callback=hndlr">
    </script>
  </body>
</html>