رابط برنامهنویسی کاربردی پرسوجو (Query API) روشهای جستجو و پیشنهاد را برای ساخت رابط جستجو یا جاسازی نتایج جستجو در یک برنامه ارائه میدهد.
برای برنامههای وب با حداقل نیازها، استفاده از ویجت جستجو را در نظر بگیرید. برای اطلاعات بیشتر، به ایجاد رابط جستجو با ویجت جستجو مراجعه کنید.
ساخت رابط جستجو
ساخت یک رابط جستجوی مینیمال نیاز به چندین مرحله دارد:
- پیکربندی یک برنامه جستجو
- ایجاد اعتبارنامههای OAuth برای برنامه
- پرس و جو از ایندکس
- نمایش نتایج پرس و جو
شما میتوانید رابط جستجو را با ویژگیهایی مانند صفحهبندی، مرتبسازی، فیلتر کردن، جنبهها و پیشنهاد خودکار، بهبود بخشید.
پیکربندی یک برنامه جستجو
شما باید حداقل یک برنامه جستجو ایجاد کنید تا با هر رابط جستجویی که ایجاد میکنید مرتبط باشد. یک برنامه جستجو پارامترهای پیشفرض برای یک پرسوجو، مانند منابع داده مورد استفاده، ترتیب مرتبسازی، فیلترها و جنبههای درخواستی را فراهم میکند. در صورت نیاز، میتوانید این پارامترها را با استفاده از API پرسوجو لغو کنید.
برای اطلاعات بیشتر در مورد برنامههای جستجو، به سفارشیسازی تجربه جستجو در جستجوی ابری مراجعه کنید.
ایجاد اعتبارنامههای OAuth برای برنامه
علاوه بر مراحل موجود در پیکربندی دسترسی به API جستجوی ابری گوگل ، شما باید اعتبارنامههای OAuth را نیز برای برنامه وب ایجاد کنید. نوع اعتبارنامههایی که ایجاد میکنید به زمینهای که API در آن استفاده میشود بستگی دارد.
از اعتبارنامهها برای درخواست مجوز از طرف کاربر استفاده کنید. هنگام درخواست مجوز از دامنه https://www.googleapis.com/auth/cloud_search.query استفاده کنید.
برای اطلاعات بیشتر در مورد گزینههای OAuth و کتابخانههای کلاینت، به [پلتفرم هویت گوگل](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 ، ممکن است رشته "جستجوی شما برای عبارت جستجوی اصلیتان با نتایج کافی مطابقت نداشت. شامل نتایج برای عبارات جستجوی مشابه" را نمایش دهید.
رسیدگی به نتایج افراد
جستجوی ابری دو نوع «نتیجه مربوط به افراد» را برمیگرداند: اسناد مربوط به شخصی که نامش در پرسوجو استفاده شده است و اطلاعات کارمندی شخصی که نامش در پرسوجو استفاده شده است. نوع دوم نتیجه تابعی از ویژگی جستجوی افراد در جستجوی ابری است و نتایج چنین پرسوجویی را میتوان در فیلد structuredResults از پاسخ API پرسوجو یافت:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
تطبیق گزارشهای مستقیم
تطبیق گزارشهای مستقیم، یکی از ویژگیهای جستجوی افراد در Cloud Search است که به کاربران امکان میدهد گزارشهای مستقیم یک فرد در سازمان خود را مشاهده کنند. نتیجه در فیلد structuredResults موجود است.
برای پرسوجوهای مربوط به مدیر یا گزارشهای مستقیم یک شخص، پاسخ دارای یک assistCardProtoHolder در structuredResults است. assistCardProtoHolder فیلدی به نام cardType دارد که برابر با RELATED_PEOPLE_ANSWER_CARD خواهد بود. assistCardProtoHolder شامل کارتی به نام relatedPeopleAnswerCard است که شامل پاسخ واقعی است. این کارت شامل subject (شخصی که در پرسوجو گنجانده شده است) و relatedPeople است که مجموعهای از افراد مرتبط با subject هستند. فیلد 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تنظیم کنید.
هایلایت کردن قطعه کدها
برای موارد برگردانده شده حاوی متن ایندکس شده یا محتوای HTML، یک قطعه از محتوا برگردانده میشود. این محتوا به کاربران کمک میکند تا مرتبط بودن مورد برگردانده شده را تعیین کنند.
اگر عبارات جستجو در قطعه کد وجود داشته باشند، یک یا چند محدوده تطابق که مکان عبارات را مشخص میکنند نیز بازگردانده میشوند.
از matchRanges برای هایلایت کردن متن منطبق هنگام رندر کردن نتایج استفاده کنید. مثال جاوا اسکریپت زیر، قطعه کد را به نشانهگذاری HTML تبدیل میکند که در آن هر محدوده منطبق در یک تگ <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
}
]
}
رشته HTML حاصل عبارت است از:
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— موارد منطبق را به نوع مشخص شدهای که در یک طرحواره سفارشی تعریف شده است، محدود میکند. - فیلترهای مقداری - موارد منطبق را بر اساس یک عملگر پرس و جو و مقدار ارائه شده محدود میکند.
فیلترهای ترکیبی امکان ترکیب چندین فیلتر مقداری را در عبارات منطقی برای پرسوجوهای پیچیدهتر فراهم میکنند.
در مثال طرحواره فیلم، میتوانید محدودیت سنی را بر اساس کاربر فعلی اعمال کنید و فیلمهای موجود را بر اساس رتبهبندی MPAA محدود کنید.
{
"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"
}
}
}
]
}
]
}
}
}
]
}
]
}
نتایج را با جنبهها اصلاح کنید
وجهها ویژگیهای فهرستبندیشدهای هستند که دستهبندیهایی را برای اصلاح نتایج جستجو نشان میدهند. از وجهها برای کمک به کاربران در اصلاح تعاملی پرسشهایشان و یافتن سریعتر موارد مرتبط استفاده کنید.
وجوه (facets) را میتوان در برنامه جستجوی شما تعریف کرد و با تنظیمات موجود در پرسوجوی شما لغو نمود.
هنگام درخواست وجهها، جستجوی ابری، پرتکرارترین مقادیر را برای ویژگیهای درخواستی در بین موارد منطبق محاسبه میکند. این مقادیر در پاسخ بازگردانده میشوند. از این مقادیر برای ساخت فیلترهایی استفاده کنید که نتایج را در درخواستهای بعدی محدود میکنند.
الگوی تعامل معمول با جنبهها به شرح زیر است:
- یک پرس و جوی اولیه انجام دهید که مشخص کند کدام ویژگیها باید در نتایج وجه لحاظ شوند.
- نتایج جستجو و وجه را رندر کنید.
- کاربر یک یا چند مقدار وجهی را برای اصلاح نتایج انتخاب میکند.
- پرس و جو را با فیلتری بر اساس مقادیر انتخاب شده تکرار کنید.
برای مثال، برای فعال کردن اصلاح پرسوجوهای فیلم بر اساس سال و رتبهبندی MPAA، ویژگی facetOptions را در پرسوجو وارد کنید.
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
نتایج وجهی با فیلدهای مبتنی بر عدد صحیح
همچنین میتوانید نتایج درخواست وجه را با فیلدهای مبتنی بر عدد صحیح، وجهبندی کنید. برای مثال، میتوانید یک ویژگی عدد صحیح به نام book_pages را به عنوان وجهبندی علامتگذاری کنید تا نتایج جستجوی کتابهایی با "100-200" صفحه را اصلاح کنید.
وقتی طرحواره فیلد ویژگی عدد صحیح خود را تنظیم میکنید، isFacetable روی true تنظیم کنید و گزینههای سطلبندی مربوطه را به integerPropertyOptions اضافه کنید. این تضمین میکند که هر ویژگی integer-facetable دارای گزینههای سطلبندی پیشفرض تعریف شده باشد.
هنگام تعریف منطق گزینههای سطلبندی، آرایهای از مقادیر افزایشی که نشاندهنده محدودهها هستند را ارائه دهید. برای مثال، اگر کاربر نهایی محدودهها را به صورت 2, 5, 10, 100 مشخص کند، آنگاه وجوه برای <2 ، [2-5) ، [5-10) ، [10-100) و >=100 محاسبه میشوند.
شما میتوانید با تعریف گزینههای سطلبندی مشابه برای facetOptions در درخواست، وجوه مبتنی بر عدد صحیح را لغو کنید. در صورت نیاز، Cloud Search از گزینههای سطلبندی تعریفشده در طرحواره استفاده میکند، زمانی که نه برنامه جستجو و نه درخواست پرسوجو گزینههای وجهی تعریفشده نداشته باشند. وجوه تعریفشده در پرسوجو بر وجوه تعریفشده در برنامه جستجو اولویت دارند و وجوه تعریفشده در برنامه جستجو بر وجوه تعریفشده در طرحواره اولویت دارند.
نتایج وجهی بر اساس اندازه یا تاریخ سند
شما میتوانید از عملگرهای رزرو شده برای اصلاح نتایج جستجو بر اساس اندازه فایل سند، که بر حسب بایت اندازهگیری میشود، یا بر اساس زمان ایجاد یا اصلاح سند استفاده کنید. نیازی به تعریف یک طرحواره سفارشی ندارید، اما باید مقدار operatorName را در FacetOptions برنامه جستجوی خود مشخص کنید.
- برای صفحهآرایی بر اساس اندازه سند،
itemsizeاستفاده کنید و گزینههای bucketing را تعریف کنید. - برای صفحهآرایی بر اساس تاریخ ایجاد سند، از
createddatetimestampاستفاده کنید. - برای صفحهآرایی بر اساس تاریخ تغییر سند،
lastmodifiedاستفاده کنید.
تفسیر سطلهای وجهی
ویژگی facetResults در پاسخ جستجوی جستجو، درخواست فیلتر دقیق کاربر را در فیلد filter برای هر bucket درج میکند.
برای وجوهی که مبتنی بر اعداد صحیح نیستند، facetResults شامل یک ورودی برای هر ویژگی درخواستی است. برای هر ویژگی، فهرستی از مقادیر یا محدودهها، به نام buckets ، ارائه میشود. مقادیری که بیشترین تکرار را دارند، ابتدا ظاهر میشوند.
وقتی کاربر یک یا چند مقدار را برای فیلتر کردن انتخاب میکند، یک پرسوجوی جدید با فیلترهای انتخابشده ایجاد کنید و دوباره از API پرسوجو کنید.
افزودن پیشنهادها
از API پیشنهادی برای ارائه تکمیل خودکار برای پرسوجوها بر اساس سابقه پرسوجوی شخصی کاربر و همچنین مخاطبین و مجموعه اسناد او استفاده کنید.
برای مثال، فراخوانی زیر پیشنهادهایی برای عبارت ناقص jo ارائه میدهد.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
سپس میتوانید پیشنهادهای حاصل را متناسب با کاربرد خود نمایش دهید.