क्वेरी एपीआई की मदद से खोज इंटरफ़ेस बनाना

क्वेरी एपीआई, खोज इंटरफ़ेस बनाने या किसी ऐप्लिकेशन में खोज के नतीजे एम्बेड करने के लिए, खोज और सुझाव के तरीके उपलब्ध कराता है.

कम ज़रूरी शर्तों वाले वेब ऐप्लिकेशन के लिए, खोज विजेट का इस्तेमाल करें. ज़्यादा जानकारी के लिए, खोज विजेट की मदद से सर्च इंटरफ़ेस बनाना देखें

सर्च इंटरफ़ेस बनाना

कम से कम खोज इंटरफ़ेस बनाने के लिए, कई चरणों की ज़रूरत होती है:

  1. सर्च ऐप्लिकेशन कॉन्फ़िगर करें
  2. ऐप्लिकेशन के लिए OAuth क्रेडेंशियल जनरेट करें
  3. इंडेक्स पर क्वेरी करें
  4. क्वेरी के नतीजे दिखाएं

पेजिंग, क्रम से लगाना, फ़िल्टर करना, पहलू, और अपने-आप सुझाव देने जैसी सुविधाओं की मदद से, खोज के इंटरफ़ेस को बेहतर बनाया जा सकता है.

सर्च ऐप्लिकेशन कॉन्फ़िगर करें

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

खोज ऐप्लिकेशन के बारे में ज़्यादा जानकारी के लिए, Cloud Search में खोज के अनुभव को पसंद के मुताबिक बनाना देखें.

ऐप्लिकेशन के लिए OAuth क्रेडेंशियल जनरेट करें

Google Cloud Search API का ऐक्सेस कॉन्फ़िगर करें में दिए गए चरणों के अलावा, आपको वेब ऐप्लिकेशन के लिए OAuth क्रेडेंशियल भी जनरेट करने होंगे. आपके बनाए गए क्रेडेंशियल इस बात पर निर्भर करते हैं कि एपीआई का इस्तेमाल किस तरह का है.

उपयोगकर्ता की ओर से अनुमति का अनुरोध करने के लिए, क्रेडेंशियल का इस्तेमाल करें. अनुमति का अनुरोध करते समय, स्कोप https://www.googleapis.com/auth/cloud_search.query का इस्तेमाल करें.

OAuth के विकल्पों और क्लाइंट लाइब्रेरी के बारे में ज़्यादा जानने के लिए, [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}) देखें.

इंडेक्स पर क्वेरी करें

इंडेक्स के हिसाब से खोजने के लिए, search तरीके का इस्तेमाल करें.

हर अनुरोध में दो तरह की जानकारी होनी चाहिए: एक टेक्स्ट query, जिससे आइटम का मिलान किया जा सके और searchApplicationId सर्च ऐप्लिकेशन का इस्तेमाल करने के लिए आईडी की पहचान करता है.

नीचे दिया गया स्निपेट, फ़िल्म टाइटैनिक फ़िल्म के डेटा सोर्स को क्वेरी दिखाता है:

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  },
}

क्वेरी के नतीजे दिखाएं

कम से कम, सर्च इंटरफ़ेस में title आइटम के साथ-साथ मूल आइटम का लिंक भी दिखना चाहिए. खोज के नतीजों में दिखने वाली अतिरिक्त जानकारी का इस्तेमाल करके, खोज के नतीजों को बेहतर तरीके से दिखाया जा सकता है. जैसे, स्निपेट और मेटाडेटा.

पूरक नतीजों को मैनेज करना

डिफ़ॉल्ट रूप से, Cloud Search तब पूरक नतीजे दिखाता है, जब उपयोगकर्ता की क्वेरी के लिए अधूरे नतीजे होते हैं. रिस्पॉन्स में मौजूद queryInterpretation फ़ील्ड से पता चलता है कि पूरक नतीजे कब दिखाए जाते हैं. अगर सिर्फ़ पूरक नतीजे दिखाए जाते हैं, तो InterpretationType को REPLACE पर सेट किया जाता है. अगर मूल क्वेरी के कुछ नतीजे पूरक नतीजों के साथ दिखते हैं, तो InterpretationType को BLEND पर सेट किया जाता है. दोनों ही मामलों में QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.

जब कुछ पूरक नतीजे लौटाए जाते हैं, तो यह बताने के लिए टेक्स्ट दें कि पूरक नतीजे वापस मिले हैं. उदाहरण के लिए, REPLACE के मामले में, हो सकता है कि आपको “आपकी मूल क्वेरी के लिए आपकी खोज का किसी भी नतीजे से मिलान न हुआ” स्ट्रिंग दिखे. मिलती-जुलती क्वेरी के लिए नतीजे दिखाए जा रहे हैं.”

BLEND के मामले में, हो सकता है कि आपको यह स्ट्रिंग दिखे: "आपकी ओरिजनल क्वेरी के लिए आपकी खोज, ज़रूरत के मुताबिक नतीजे नहीं मिली. इसमें मिलती-जुलती क्वेरी के नतीजे शामिल हैं."

लोगों के खोज नतीजे मैनेज करना

Cloud Search दो तरह के "लोगों के नतीजे" दिखाता है: किसी व्यक्ति से जुड़े ऐसे दस्तावेज़ जिसका नाम क्वेरी में इस्तेमाल किया जाता है और उस व्यक्ति के लिए कर्मचारी की जानकारी जिसका नाम क्वेरी में इस्तेमाल किया गया है. बाद वाला नतीजा, Cloud Search की लोगों को खोजने की सुविधा का इस्तेमाल करता है और ऐसी क्वेरी के नतीजे, क्वेरी एपीआई के जवाब के structuredResults फ़ील्ड में देखे जा सकते हैं:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

प्रत्यक्ष रिपोर्ट मैचिंग

डायरेक्ट रिपोर्ट मैचिंग, Cloud Search की लोगों को खोजने की सुविधा है. इसकी मदद से, उपयोगकर्ता अपने संगठन के किसी व्यक्ति की रिपोर्ट सीधे देख सकते हैं. यह नतीजा, structuredResults फ़ील्ड में उपलब्ध है.

किसी व्यक्ति के मैनेजर या डायरेक्ट रिपोर्ट के बारे में की गई क्वेरी के लिए, जवाब के तौर पर structuredResults में एक assistCardProtoHolder दिया जाता है. assistCardProtoHolder में cardType नाम का एक फ़ील्ड होता है, जो RELATED_PEOPLE_ANSWER_CARD के बराबर होगा. assistCardProtoHolder में relatedPeopleAnswerCard नाम का एक कार्ड होता है, जिसमें असल जवाब होता है. इसमें subject (क्वेरी में शामिल किया गया व्यक्ति) और relatedPeople शामिल हैं, जो कि विषय से जुड़े लोगों का एक सेट है. relationType फ़ील्ड, MANAGER या DIRECT_REPORTS वैल्यू दिखाता है.

यह कोड, क्वेरी से मिलती-जुलती डायरेक्ट रिपोर्ट के लिए रिस्पॉन्स का एक उदाहरण दिखाता है:

{
  "results": [],
  "structuredResults": [{
    "assistCardProtoHolder": {
      "extensions": {
        "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
        "cardMetadata": {
          "cardCategory": "ANSWER"
        },
        "cardType": "RELATED_PEOPLE_ANSWER_CARD",
        "relatedPeopleAnswerCard": {
          "subject": {
            "email": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

पूरक नतीजों सहित ऑप्टिमाइज़ेशन बंद करें

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

  • खोज ऐप्लिकेशन-लेवल पर, सभी ऑप्टिमाइज़ेशन बंद करने के लिए, खोज ऐप्लिकेशन में QueryInterpretationConfig.force_verbatim_mode को true पर सेट करें. इनमें, पूरक नतीजे, समानार्थी शब्द, और स्पेलिंग सुधार भी शामिल हैं.

  • खोज क्वेरी-लेवल पर सभी ऑप्टिमाइज़ेशन बंद करने के लिए, खोज क्वेरी में QueryInterpretationOptions.enableVerbatimMode को true पर सेट करें. इसमें, पूरक नतीजे, समानार्थी शब्द, और स्पेलिंग सुधार भी शामिल हैं.

  • खोज ऐप्लिकेशन-लेवल पर पूरक नतीजे बंद करने के लिए, खोज क्वेरी में QueryInterpretationOptions.forceDisableSupplementalResults को true पर सेट करें.

  • खोज क्वेरी-लेवल पर पूरक नतीजे बंद करने के लिए, खोज क्वेरी में QueryInterpretationOptions.disableSupplementalResults को true पर सेट करें.

स्निपेट हाइलाइट करें

इंडेक्स किए गए टेक्स्ट या एचटीएमएल कॉन्टेंट वाले लौटाए गए आइटम के लिए, कॉन्टेंट का एक स्निपेट दिया जाता है. इस कॉन्टेंट से, उपयोगकर्ताओं को यह तय करने में मदद मिलती है कि लाए आइटम कितने काम के हैं.

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

नतीजों को रेंडर करते समय, मेल खाने वाले टेक्स्ट को हाइलाइट करने के लिए matchRanges का इस्तेमाल करें. नीचे दिया गया JavaScript उदाहरण, स्निपेट को एचटीएमएल मार्कअप में बदल देता है. इसमें, हर मैचिंग रेंज को <span> टैग में रैप किया जाता है.

function highlightSnippet(snippet) {
  let text = snippet.snippet;
  let formattedText = text;
  if (snippet.matchRanges) {
    let parts = [];
    let index = 0;
    for (let match of snippet.matchRanges) {
      let start = match.start || 0; // Default to 0 if omitted
      let end = match.end;
      if (index < start) { // Include any leading text before/between ranges
        parts.push(text.slice(index, start));
      }
      parts.push('<span class="highlight">');
      parts.push(text.slice(start, end));
      parts.push('</span>');
      index = end;
    }
    parts.push(text.slice(index)); // Include any trailing text after last range
    formattedText = parts.join('');
  }
  return formattedText;
}

स्निपेट के आधार पर:

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

इससे मिलने वाली एचटीएमएल स्ट्रिंग:

This is an <span class="highlight">example</span> snippet...

मेटाडेटा दिखाएं

metadata फ़ील्ड का इस्तेमाल करके, लौटाए गए आइटम के बारे में ऐसी अतिरिक्त जानकारी देखें जो उपयोगकर्ताओं के काम की हो. metadata फ़ील्ड में आइटम का createTime और updateTime शामिल होता है. साथ ही, आइटम से जुड़ा ऐसा स्ट्रक्चर्ड डेटा भी शामिल होता है जिसे लौटाया जा सकता है.

स्ट्रक्चर्ड डेटा दिखाने के लिए, displayOptions फ़ील्ड का इस्तेमाल करें. displayOptions फ़ील्ड में, ऑब्जेक्ट टाइप के लिए डिसप्ले लेबल और metalines का सेट होता है. हर मेटालाइन, डिसप्ले लेबल और वैल्यू पेयर का ऐरे होता है, जैसा कि स्कीमा में कॉन्फ़िगर किया गया है.

अतिरिक्त नतीजे पाएं

अतिरिक्त नतीजे पाने के लिए, अनुरोध में start फ़ील्ड को पसंद के मुताबिक ऑफ़सेट पर सेट करें. pageSize फ़ील्ड से हर पेज के साइज़ में बदलाव किया जा सकता है.

लौटाए गए आइटम की संख्या दिखाने या लौटाए गए आइटम की मदद से पेज पर पेजिंग कंट्रोल दिखाने के लिए, resultCount फ़ील्ड का इस्तेमाल करें. नतीजे के सेट के साइज़ के आधार पर, असल वैल्यू या अनुमानित वैल्यू दी जाती है.

नतीजों को क्रम से लगाएं

sortOptions फ़ील्ड का इस्तेमाल करके, लौटाए गए आइटम का क्रम बताएं. sortOptions वैल्यू, दो फ़ील्ड वाला एक ऑब्जेक्ट है:

  • operatorName — स्ट्रक्चर्ड डेटा प्रॉपर्टी को क्रम से लगाने के लिए इस्तेमाल किया जाने वाला ऑपरेटर. एक से ज़्यादा ऑपरेटर वाली प्रॉपर्टी को सिर्फ़ मुख्य इक्वलिटी ऑपरेटर का इस्तेमाल करके क्रम से लगाया जा सकता है.
  • sortOrder — क्रम से लगाने की दिशा, ASCENDING या DESCENDING.

'कितने काम का है' का इस्तेमाल, क्रम में लगाने की दूसरी कुंजी के तौर पर भी किया जाता है. अगर किसी क्वेरी में क्रम से लगाने का कोई क्रम तय नहीं किया गया है, तो नतीजे सिर्फ़ इस आधार पर रैंक किए जाते हैं कि वे कितने काम के हैं.

"sortOptions": {
  "operatorName": "priority",
  "sortOrder": "DESCENDING"
}

फ़िल्टर जोड़ना

क्वेरी एक्सप्रेशन के अलावा, फ़िल्टर लागू करके नतीजों को सीमित किया जा सकता है. सर्च ऐप्लिकेशन और खोज अनुरोध, दोनों के लिए फ़िल्टर इस्तेमाल किए जा सकते हैं.

किसी अनुरोध या खोज ऐप्लिकेशन में फ़िल्टर जोड़ने के लिए, dataSourceRestrictions.filterOptions[] फ़ील्ड में फ़िल्टर जोड़ें.

डेटा सोर्स को ज़्यादा फ़िल्टर करने के दो मुख्य तरीके हैं:

  • filterOptions[].objectType प्रॉपर्टी की मदद से ऑब्जेक्ट फ़िल्टर, कस्टम स्कीमा में बताए गए खास टाइप से मिलते-जुलते आइटम पर पाबंदी लगाता है.
  • वैल्यू फ़िल्टरक्वेरी ऑपरेटर और दी गई वैल्यू के आधार पर, मिलते-जुलते आइटम पर पाबंदी लगाता है.

कंपोज़िट फ़िल्टर की मदद से, ज़्यादा मुश्किल क्वेरी के लिए कई वैल्यू फ़िल्टर को लॉजिकल एक्सप्रेशन में मिलाया जा सकता है.

फ़िल्म स्कीमा वाले उदाहरण में, मौजूदा उपयोगकर्ता के हिसाब से उम्र की सीमा लागू की जा सकती है और एमपीएए रेटिंग के हिसाब से उपलब्ध फ़िल्मों पर पाबंदी लगाई जा सकती है.

{
  "query": "adventure",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>"
  },
  "dataSourceRestrictions": [
    {
      "source": {
        "name": "datasources/<data_source_id>"
      },
      "filterOptions": [
        {
          "objectType": "movie",
          "filter": {
            "compositeFilter": {
              "logicOperator": "AND"
              "subFilters": [
                {
                  "compositeFilter": {
                  "logicOperator": "OR"
                  "subFilters": [
                    {
                      "valueFilter": {
                        "operatorName": "rated",
                        "value": {
                          "stringValue": "G"
                        }
                      }
                    },
                    {
                      "valueFilter": {
                        "operatorName": "rated",
                        "value": {
                          "stringValue": "PG"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

अलग-अलग पहलुओं की मदद से नतीजों को बेहतर बनाना

फ़ेसेट, इंडेक्स की गई ऐसी प्रॉपर्टी हैं जो खोज के नतीजों को बेहतर बनाने के लिए कैटगरी दिखाती हैं. पहलुओं का इस्तेमाल करें, ताकि उपयोगकर्ता अपनी क्वेरी को इंटरैक्टिव तरीके से बेहतर बना सकें और काम के आइटम तेज़ी से ढूंढ सकें.

पहलू आपके सर्च ऐप्लिकेशन में तय किए जा सकते हैं. और इन्हें आपकी क्वेरी में मौजूद सेटिंग के ज़रिए बदला जा सकता है.

पहलुओं का अनुरोध करते समय, Cloud Search मेल खाने वाले आइटम में से अनुरोध की गई प्रॉपर्टी के लिए सबसे ज़्यादा बार आने वाली वैल्यू का हिसाब लगाता है. ये वैल्यू रिस्पॉन्स में दिखती हैं. इन वैल्यू का इस्तेमाल ऐसे फ़िल्टर बनाने के लिए करें जो बाद की क्वेरी के नतीजों को सटीक बनाएं.

अलग-अलग पहलुओं के साथ इंटरैक्शन का सामान्य पैटर्न यह है:

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

उदाहरण के लिए, साल और एमपीएए रेटिंग के हिसाब से फ़िल्म की क्वेरी को बेहतर बनाने की सुविधा चालू करने के लिए, क्वेरी में facetOptions प्रॉपर्टी शामिल करें.

"facetOptions": [
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "year"
  },
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "rated"
  }
]

पूर्णांक-आधारित फ़ील्ड वाले पहलू नतीजे

पूर्णांक-आधारित फ़ील्ड के साथ भी नतीजों का अनुरोध किया जा सकता है. उदाहरण के लिए, "100-200" पेजों वाली किताबों के बारे में खोज के नतीजों को बेहतर बनाने के लिए, book_pages नाम की इंटीजर प्रॉपर्टी को फ़ेसटेबल के तौर पर मार्क किया जा सकता है.

पूर्णांक प्रॉपर्टी फ़ील्ड स्कीमा सेट अप करते समय, isFacetable को true पर सेट करें. इसके बाद, integerPropertyOptions में इससे जुड़े बकेटिंग विकल्प जोड़ें. इससे यह पक्का होता है कि हर पूर्णांक की सुविधा वाली प्रॉपर्टी में, डिफ़ॉल्ट बकेटिंग के विकल्प तय होते हैं.

बकेटिंग विकल्प लॉजिक तय करते समय, बताने वाली रेंज की इंक्रीमेंटल वैल्यू वाला ऐरे दें. उदाहरण के लिए, अगर असली उपयोगकर्ता रेंज को 2, 5, 10, 100 के तौर पर बताता है, तो <2, [2-5), [5-10), [10-100), >=100 के लिए अलग-अलग पहलुओं को कैलकुलेट किया जाता है.

अनुरोध में, बकेटिंग के यही विकल्प facetOptions को तय करके, पूर्णांक पर आधारित पहलुओं को बदला जा सकता है. ज़रूरत पड़ने पर, Cloud Search, स्कीमा में बताए गए बकेटिंग के विकल्पों का इस्तेमाल करता है. ऐसा तब किया जाता है, जब खोज ऐप्लिकेशन या क्वेरी अनुरोध में, पहलू के विकल्प तय नहीं किए गए हों. क्वेरी में परिभाषित किए गए पहलुओं को खोज ऐप्लिकेशन में तय किए गए पहलुओं की तुलना में प्राथमिकता दी जाती है और खोज ऐप्लिकेशन में तय किए गए पहलुओं को स्कीमा में बताए गए पहलुओं की तुलना में प्राथमिकता मिलती है.

दस्तावेज़ के साइज़ या तारीख के हिसाब से पहलू नतीजे

दस्तावेज़ की फ़ाइल के साइज़, बाइट में या किसी दस्तावेज़ को बनाने या उसमें बदलाव करने के समय के आधार पर, खोज के नतीजों को बेहतर बनाने के लिए, रिज़र्व किए गए ऑपरेटर इस्तेमाल किए जा सकते हैं. आपको कस्टम स्कीमा तय करने की ज़रूरत नहीं है, लेकिन आपको अपने खोज ऐप्लिकेशन के FacetOptions में operatorName वैल्यू ज़रूर बतानी होगी.

  • दस्तावेज़ के साइज़ के हिसाब से डेटा फ़िल्टर करने के लिए, itemsize का इस्तेमाल करें और बकेटिंग के विकल्प तय करें.
  • दस्तावेज़ बनाने की तारीख के हिसाब से डेटा फ़िल्टर करने के लिए, createddatetimestamp का इस्तेमाल करें.
  • दस्तावेज़ में बदलाव करने की तारीख के हिसाब से डेटा फ़िल्टर करने के लिए, lastmodified का इस्तेमाल करें.

फ़ैसेट बकेट की व्याख्या करना

खोज क्वेरी के जवाब में मौजूद facetResults प्रॉपर्टी में, filter फ़ील्ड में हर bucket के लिए उपयोगकर्ता का फ़िल्टर करने का सटीक अनुरोध शामिल होता है.

पूर्णांक पर आधारित नहीं पहलुओं के लिए, facetResults में अनुरोध की गई हर प्रॉपर्टी की एंट्री शामिल होती है. हर प्रॉपर्टी के लिए, वैल्यू या रेंज की एक सूची दी जाती है जिसे buckets कहा जाता है. सबसे ज़्यादा बार आने वाली वैल्यू पहले दिखती हैं.

जब कोई उपयोगकर्ता फ़िल्टर करने के लिए एक या उससे ज़्यादा वैल्यू चुनता है, तो चुने गए फ़िल्टर के साथ एक नई क्वेरी बनाएं और एपीआई से दोबारा क्वेरी करें.

सुझाव जोड़ें

उपयोगकर्ता के निजी क्वेरी इतिहास, संपर्कों, और उसके दस्तावेज़ों के संग्रह के आधार पर क्वेरी के लिए अपने-आप पूरा होने की सुविधा देने के लिए, सुझाव एपीआई का इस्तेमाल करें.

उदाहरण के लिए, नीचे दिया गया कॉल अधूरे वाक्यांश jo के लिए सुझाव देता है.

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

फिर आप मिलने वाले सुझावों को अपने आवेदन के मुताबिक दिखा सकते हैं.