एपीआई शुरू करने के लिए REST का इस्तेमाल करना

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

अनुरोध करना

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

आप एक एचटीटीपी 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 पर लागू होते हैं और खोज के अनुरोधों की खास जानकारी reference.

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

Custom Search JSON एपीआई से जुड़ी सभी कार्रवाइयों पर लागू होने वाले क्वेरी पैरामीटर सिस्टम पैरामीटर.

जवाब का डेटा

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

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

• अनुरोध की गई खोज (और संभावित रूप से संबंधित खोज अनुरोधों) के बारे में बताने वाला मेटाडेटा
• Programmable Search Engine की जानकारी देने वाला मेटाडेटा
• खोज के नतीजे

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

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

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

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

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

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

खोज के नतीजे

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

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

JavaScript से REST

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

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

<html>
  <head>
    <title>Custom Search JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; 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=cars&callback=hndlr">
    </script>
  </body>
</html>