رابط برنامهنویسی کاربردی پرسوجو (Query API) روشهای جستجو و پیشنهاد را برای ساخت رابط جستجو یا جاسازی نتایج در یک برنامه ارائه میدهد.
برای برنامههای وب با حداقل نیازها، استفاده از ویجت جستجو را در نظر بگیرید. به بخش «ایجاد رابط جستجو با ویجت جستجو» مراجعه کنید.
ساخت رابط جستجو
ساخت یک رابط جستجوی مینیمال نیاز به چندین مرحله دارد:
- یک برنامه جستجو پیکربندی کنید.
- اعتبارنامههای OAuth را برای برنامه ایجاد کنید.
- از ایندکس پرس و جو کنید.
- نتایج پرس و جو را نمایش دهید.
شما میتوانید رابط کاربری را با ویژگیهایی مانند صفحهبندی، مرتبسازی، فیلتر کردن، جنبهها و تکمیل خودکار بهبود بخشید.
پیکربندی یک برنامه جستجو
شما باید حداقل یک برنامه جستجو برای هر رابط جستجو ایجاد کنید. یک برنامه جستجو پارامترهای پیشفرضی مانند منابع داده، ترتیب مرتبسازی، فیلترها و جنبهها را ارائه میدهد. میتوانید این پارامترها را با استفاده از API پرسوجو لغو کنید.
شما نمیتوانید تعداد منابع داده مورد استفاده در یک پرسوجو را فراتر از تعداد منابع پیکربندیشده در برنامه جستجو افزایش دهید. میتوانید با استفاده dataSourceRestrictions یک پرسوجو را به زیرمجموعهای از این منابع محدود کنید.
برای اطلاعات بیشتر، به سفارشیسازی تجربه جستجو مراجعه کنید.
ایجاد اعتبارنامههای OAuth برای برنامه
علاوه بر مراحل موجود در پیکربندی دسترسی به Cloud Search API ، باید اعتبارنامههای OAuth را برای برنامه وب خود ایجاد کنید.
از اعتبارنامهها برای درخواست مجوز از طرف کاربر استفاده کنید. از دامنه https://www.googleapis.com/auth/cloud_search.query استفاده کنید.
برای اطلاعات بیشتر در مورد گزینههای OAuth، به Google Identity Platform مراجعه کنید.
پرس و جو از ایندکس
برای جستجوی فهرست از روش search استفاده کنید.
هر درخواست باید شامل یک query متنی و یک searchApplicationId باشد.
این مثال از یک منبع داده فیلم پرس و جو میکند:
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
}
}
نمایش نتایج پرس و جو
رابطهای جستجو باید title آیتم و پیوندی به آیتم اصلی را نمایش دهند. همچنین میتوانید از قطعه کدها و فرادادهها برای بهبود نمایش استفاده کنید.
نتایج تکمیلی را مدیریت کنید
جستجوی ابری (Cloud Search) زمانی که تعداد نتایج منطبق با یک پرسوجو کافی نباشد، نتایج تکمیلی را برمیگرداند. فیلد queryInterpretation این را نشان میدهد. اگر فقط نتایج تکمیلی برگردانده شوند، InterpretationType REPLACE است. اگر آنها با هم ترکیب شوند، BLEND خواهد بود.
هنگام بازگرداندن نتایج تکمیلی، اطلاعرسانی به کاربر را در نظر داشته باشید. برای REPLACE ، میتوانید بگویید: "جستجوی شما با هیچ نتیجهای مطابقت نداشت. نمایش نتایج برای عبارات مشابه."
رسیدگی به نتایج افراد
جستجوی ابری با استفاده از ویژگی جستجوی افراد، اسناد مربوط به افراد و اطلاعات کارمندان را برمیگرداند. نتایج در فیلد structuredResults قرار دارند:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
تطبیق گزارشهای مستقیم
تطبیق گزارشهای مستقیم به کاربران امکان میدهد گزارشهای مستقیم یک شخص را مشاهده کنند. پاسخ شامل یک assistCardProtoHolder با cardType RELATED_PEOPLE_ANSWER_CARD است.
غیرفعال کردن بهینهسازیها
بهینهسازیهایی مانند نتایج تکمیلی به طور پیشفرض فعال هستند. میتوانید آنها را غیرفعال کنید:
- جستجوی سطح برنامه :
force_verbatim_modeرا رویtrueتنظیم کنید. - سطح پرسوجو :
enableVerbatimModeرا رویtrueتنظیم کنید.
هایلایت کردن قطعه کدها
جستجوی ابری، قطعه کدی برای متن فهرستبندی شده یا HTML برمیگرداند. اگر عبارات جستجو وجود داشته باشند، matchRanges مکان آنها را مشخص میکند. از این محدودهها برای برجسته کردن متن استفاده کنید.
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 برای اطلاعاتی مانند createTime ، updateTime و دادههای ساختاریافته استفاده کنید. displayOptions برای نمایش دادههای ساختاریافته استفاده کنید.
بازیابی نتایج اضافی
برای بازیابی نتایج بیشتر، فیلد start را روی مقدار offset انتخاب شده تنظیم کنید. اندازه صفحه را با pageSize تنظیم کنید. resultCount برای نمایش کل موارد یا تعداد تخمینی استفاده کنید.
مرتبسازی نتایج
برای مشخص کردن ترتیب sortOptions استفاده کنید:
-
operatorName: ویژگیای که قرار است بر اساس آن مرتبسازی انجام شود. -
sortOrder:ASCENDINGیاDESCENDING.
مرتبط بودن، کلید مرتبسازی پیشفرض و ثانویه است.
فیلترها را اضافه کنید
نتایج را با استفاده از فیلترها در برنامه یا درخواست جستجو محدود کنید. اگر هر دو فیلترها را برای یک منبع مشخص کنند، هر دو باید درست ارزیابی شوند.
فیلترها را در dataSourceRestrictions.filterOptions[] اعمال کنید. انواع فیلترهای اصلی:
- فیلترهای شیء : موارد منطبق را به یک نوع خاص محدود میکند.
- فیلترهای مقداری : موارد منطبق را بر اساس یک عملگر و مقدار محدود کنید.
فیلترهای مرکب، فیلترهای چند مقداری را با هم ترکیب میکنند.
نتایج را با جنبهها اصلاح کنید
وجهها به کاربران کمک میکنند تا به صورت تعاملی پرسوجوها را اصلاح کنند. وقتی وجهها را درخواست میکنید، جستجوی ابری پرتکرارترین مقادیر را برای آن ویژگیها محاسبه میکند.
الگوی معمول: ۱. پرسوجو با مشخص کردن ویژگیهای رویهای. ۱. نمایش نتایج جستجو و رویهای. ۱. کاربر مقادیر رویهای را انتخاب میکند. ۱. پرسوجو را با فیلتری بر اساس انتخابها تکرار میکند.
نتایج وجهی با فیلدهای مبتنی بر عدد صحیح
یک ویژگی عدد صحیح را به عنوان facetable علامت گذاری کنید تا نتایج بر اساس محدودهها اصلاح شوند (مثلاً "100-200" صفحه). isFacetable روی true تنظیم کنید و گزینههای پیشفرض bucketing را در طرحواره تعریف کنید.
نتایج وجهی بر اساس اندازه یا تاریخ سند
استفاده از عملگرهای رزرو شده :
-
itemsize: برای اندازه فایل بر حسب بایت. -
createddatetimestamp: برای تاریخ ایجاد. -
lastmodified: برای تاریخ اصلاح.
افزودن پیشنهادها
از API پیشنهادی برای تکمیل خودکار بر اساس تاریخچه پرس و جو، مخاطبین و محتوای سند استفاده کنید.