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

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

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

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

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

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. चुनी गई वैल्यू के आधार पर, फ़िल्टर के साथ क्वेरी दोहराएं.

उदाहरण के लिए, साल और MPAA रेटिंग के हिसाब से मूवी क्वेरी को बेहतर बनाने के लिए, क्वेरी में 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 प्रॉपर्टी में, हर bucket के लिए filter फ़ील्ड में उपयोगकर्ता का सटीक फ़िल्टर अनुरोध शामिल होता है.

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

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

सुझाव जोड़ें

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

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

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

इसके बाद, अपने ऐप्लिकेशन के हिसाब से, नतीजों को अपने हिसाब से दिखाया जा सकता है.