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

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

अनुरोध करें

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

किसी खास खोज के नतीजे पाने के लिए, उसके यूआरआई पर एचटीटीपी 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

ध्यान दें: खोज के अनुरोध की लंबाई 2048 वर्णों से ज़्यादा नहीं होनी चाहिए.

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

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

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

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

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

रेफ़रंस में, अनुरोध पैरामीटर के बारे में खास जानकारी दी गई है. ये पैरामीटर, खास तौर पर 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>

ध्यान दें: cx को अपने सर्च इंजन आईडी से बदलें. पक्का करें कि आपका सर्च इंजन, क्वेरी के लिए नतीजे दिखाता हो.