توفّر Query API طريقتَي البحث والاقتراح لإنشاء واجهة بحث أو تضمين نتائج البحث في تطبيق.
بالنسبة إلى تطبيقات الويب التي تتضمّن الحد الأدنى من المتطلبات، ننصحك باستخدام أداة البحث. لمزيد من المعلومات، اطّلِع على إنشاء واجهة بحث باستخدام أداة البحث.
إنشاء واجهة بحث
يتطلّب إنشاء واجهة بحث بسيطة عدة خطوات:
- إعداد تطبيق بحث
- إنشاء بيانات اعتماد 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 يحدّد رقم التعريف الخاص بتطبيق البحث المطلوب استخدامه.
يعرض المقتطف التالي طلب بحث في مصدر بيانات الأفلام عن فيلم Titanic:
{
"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.
بالنسبة إلى طلبات البحث حول مدير أحد المستخدمين أو مرؤوسيه المباشرين، يتضمّن الرد assistCardProtoHolder ضمن structuredResults. يحتوي
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في طلب البحث.
المقتطفات البارزة
بالنسبة إلى العناصر التي تم إرجاعها والتي تحتوي على نص مفهرس أو محتوى HTML، يتم إرجاع مقتطف من المحتوى. يساعد هذا المحتوى المستخدمين في تحديد مدى صلة المنتج المعروض بطلب البحث.
إذا كانت عبارات البحث متوفّرة في المقتطف، سيتم أيضًا عرض نطاق واحد أو أكثر من نطاقات المطابقة التي تحدّد موضع العبارات.
استخدِم matchRanges لتمييز النص المطابق عند عرض النتائج. يحوّل مثال JavaScript التالي المقتطف إلى ترميز 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"
}
}
}
]
}
]
}
}
}
]
}
]
}
تحسين النتائج باستخدام عوامل التصفية
الواجهات هي خصائص مفهرسة تمثّل فئات لتنقيح نتائج البحث. استخدِم عوامل التصفية لمساعدة المستخدمين في تحسين طلبات البحث بشكل تفاعلي والعثور على السلع ذات الصلة بشكل أسرع.
يمكن تحديد التصنيفات في تطبيق البحث، ويمكن إلغاؤها من خلال الإعدادات في طلب البحث.
عند طلب الأوجه، يحسب Cloud Search القيم الأكثر تكرارًا للسمات المطلوبة بين العناصر المطابقة. ويتم عرض هذه القيم في الردّ. استخدِم هاتين القيمتين لإنشاء فلاتر تضيّق نطاق النتائج في طلبات البحث اللاحقة.
نمط التفاعل المعتاد مع عوامل التصفية هو:
- إجراء طلب بحث أولي يحدّد السمات المطلوب تضمينها في نتائج البحث المتعدّد الأوجه
- عرض نتائج البحث ونتائج الفلاتر
- يختار المستخدم قيمة واحدة أو أكثر من قيم الواجهات لتحسين النتائج.
- كرِّر طلب البحث مع فلتر استنادًا إلى القيم المحدّدة.
على سبيل المثال، لتفعيل تحسين طلبات البحث عن الأفلام حسب السنة وتقييم جمعية الفيلم الأمريكية (MPAA)،
أدرِج الخاصية 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 خيارات التقسيم إلى مجموعات المحدّدة في المخطط عندما لا يتضمّن تطبيق البحث أو طلب البحث خيارات للتقسيم إلى أوجه. تحظى الواجهات المحدّدة في طلب البحث بالأولوية على الواجهات المحدّدة في تطبيق البحث، وتحظى الواجهات المحدّدة في تطبيق البحث بالأولوية على الواجهات المحدّدة في المخطط.
تقسيم النتائج حسب حجم المستند أو تاريخه
يمكنك استخدام
عوامل التشغيل المحجوزة
لتحسين نتائج البحث حسب حجم ملف المستند، مقاسًا بالبايت، أو حسب وقت إنشاء المستند أو تعديله. لست بحاجة إلى تحديد مخطط مخصّص، ولكن عليك تحديد قيمة operatorName في FacetOptions لتطبيق البحث.
- لتقسيم النتائج إلى فئات حسب حجم المستند، استخدِم
itemsizeوحدِّد خيارات التقسيم إلى فئات. - لتقسيم النتائج حسب تاريخ إنشاء المستند، استخدِم
createddatetimestamp. - لتقسيم النتائج حسب تاريخ تعديل المستند، استخدِم
lastmodified.
تفسير حزم الواجهات
تتضمّن السمة facetResults في الردّ على طلب البحث طلب الفلتر الدقيق للمستخدم في الحقل filter لكل bucket.
بالنسبة إلى التصنيفات التي لا تستند إلى أعداد صحيحة، يتضمّن facetResults إدخالاً لكل سمة مطلوبة. لكل سمة، يتم توفير قائمة بالقيم أو النطاقات، تُسمى buckets. تظهر القيم الأكثر تكرارًا أولاً.
عندما يختار المستخدم قيمة واحدة أو أكثر لإجراء فلترة وفقًا لها، أنشئ طلب بحث جديدًا يتضمّن الفلاتر المحدّدة وأرسِل طلب البحث إلى واجهة برمجة التطبيقات مرة أخرى.
إضافة اقتراحات
استخدِم واجهة برمجة التطبيقات suggest لتقديم ميزة الإكمال التلقائي لطلبات البحث استنادًا إلى سجلّ طلبات البحث الشخصي للمستخدم، بالإضافة إلى جهات الاتصال ومجموعة المستندات الخاصة به.
على سبيل المثال، يقدّم الاستدعاء التالي اقتراحات للعبارة الجزئية jo.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
يمكنك بعد ذلك عرض الاقتراحات الناتجة بالطريقة المناسبة لتطبيقك.