क्वेरी एपीआई, खोज इंटरफ़ेस बनाने या किसी ऐप्लिकेशन में खोज के नतीजे एम्बेड करने के लिए, खोज और सुझाव के तरीके उपलब्ध कराता है.
कम ज़रूरी शर्तों वाले वेब ऐप्लिकेशन के लिए, Search विजेट का इस्तेमाल करें. ज़्यादा जानकारी के लिए, Search विजेट की मदद से सर्च इंटरफ़ेस बनाना लेख पढ़ें
सर्च इंटरफ़ेस बनाना
कम से कम खोज इंटरफ़ेस बनाने के लिए, कई चरणों की ज़रूरत होती है:
- सर्च ऐप्लिकेशन कॉन्फ़िगर करें
- ऐप्लिकेशन के लिए OAuth क्रेडेंशियल जनरेट करें
- इंडेक्स के बारे में क्वेरी करें
- क्वेरी के नतीजे दिखाएं
पेजिंग, क्रम से लगाना, फ़िल्टर करना, पहलू और अपने-आप सुझाव देने जैसी सुविधाओं की मदद से, खोज के इंटरफ़ेस को बेहतर बनाया जा सकता है.
सर्च ऐप्लिकेशन कॉन्फ़िगर करें
आपको अपने बनाए गए हर सर्च इंटरफ़ेस से जोड़ने के लिए, कम से कम एक सर्च ऐप्लिकेशन बनाना होगा. सर्च ऐप्लिकेशन, क्वेरी के लिए डिफ़ॉल्ट पैरामीटर उपलब्ध कराता है. जैसे, इस्तेमाल किए जाने वाले डेटा सोर्स, क्रम से लगाने का क्रम, फ़िल्टर, और अनुरोध करने के तरीके. ज़रूरत पड़ने पर, क्वेरी एपीआई का इस्तेमाल करके इन पैरामीटर को बदला जा सकता है.
खोज ऐप्लिकेशन के बारे में ज़्यादा जानकारी के लिए, 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, मेल खाने वाले आइटम में से अनुरोध की गई प्रॉपर्टी के लिए सबसे ज़्यादा बार-बार आने वाली वैल्यू की गणना करता है. ये वैल्यू, रिस्पॉन्स के तौर पर दिखती हैं. इन वैल्यू का इस्तेमाल ऐसे फ़िल्टर बनाने के लिए करें जो बाद की क्वेरी के नतीजों को सीमित करता है.
अलग-अलग पहलुओं के साथ इंटरैक्शन का सामान्य पैटर्न:
- शुरुआती क्वेरी बनाएं. इससे यह पता चलेगा कि वेबसाइट पर दिखने वाले नतीजों में किन प्रॉपर्टी को शामिल करना है.
- खोज और मुखिका परिणामों को रेंडर करें.
- नतीजों को बेहतर बनाने के लिए, उपयोगकर्ता एक या उससे ज़्यादा फ़ैसेट वैल्यू चुनता है.
- चुनी गई वैल्यू के आधार पर, फ़िल्टर वाली क्वेरी को दोहराएं.
उदाहरण के लिए, साल के हिसाब से फ़िल्म की क्वेरी को बेहतर बनाने और एमपीएए रेटिंग की सुविधा चालू करने के लिए,
क्वेरी में facetOptions
प्रॉपर्टी शामिल करें.
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
पूर्णांक-आधारित फ़ील्ड वाले मुखिका परिणाम
पूर्णांक-आधारित फ़ील्ड के साथ भी नतीजों का अनुरोध किया जा सकता है. उदाहरण के लिए, book_pages
नाम की इंटीजर प्रॉपर्टी को फ़ेसटेबल के तौर पर मार्क किया जा सकता है. इससे "100-200" पेजों वाली किताबों के बारे में की गई खोज के नतीजों को बेहतर बनाया जा सकता है.
अपनी इंटीजर प्रॉपर्टी का फ़ील्ड स्कीमा सेट अप करते समय, 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
कहा जाता है. सबसे ज़्यादा बार आने वाली वैल्यू पहले दिखती हैं.
जब कोई उपयोगकर्ता फ़िल्टर करने के लिए एक या उससे ज़्यादा वैल्यू चुनता है, तो चुने गए फ़िल्टर से एक नई क्वेरी बनाएं और एपीआई से फिर से क्वेरी करें.
सुझाव जोड़ें
उपयोगकर्ता की निजी क्वेरी के इतिहास, संपर्कों, और उनके दस्तावेज़ों के संग्रह के आधार पर, क्वेरी के अपने-आप पूरे होने की सुविधा देने के लिए, suggest API का इस्तेमाल करें.
उदाहरण के लिए, नीचे दिया गया कॉल आंशिक वाक्यांश jo के लिए सुझाव देता है.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
फिर आप मिलने वाले सुझावों को अपने आवेदन के मुताबिक दिखा सकते हैं.