توفر واجهة برمجة تطبيقات طلبات البحث طرقًا للبحث والاقتراح لإنشاء واجهة بحث أو تضمين نتائج البحث في أحد التطبيقات.
بالنسبة إلى تطبيقات الويب ذات الحد الأدنى من المتطلبات، يمكنك استخدام أداة البحث. ولمزيد من المعلومات، يُرجى الاطّلاع على إنشاء واجهة بحث باستخدام أداة البحث.
إنشاء واجهة بحث
يتطلب إنشاء الحد الأدنى من واجهة البحث عدة خطوات:
- ضبط تطبيق بحث
- إنشاء بيانات اعتماد 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
كـ "facetable" لتحسين نتائج البحث عن كتب تحتوي على صفحات "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"
}
}
يمكنك عندئذٍ عرض الاقتراحات الناتجة حسبما يلائم تطبيقك.