إنشاء واجهة بحث باستخدام Query API

توفّر Query API طريقتَي البحث والاقتراح لإنشاء واجهة بحث أو تضمين النتائج في تطبيق.

بالنسبة إلى تطبيقات الويب التي تتطلّب الحد الأدنى من المتطلبات، ننصحك باستخدام أداة البحث. يمكنك الاطّلاع على مقالة إنشاء واجهة بحث باستخدام أداة البحث.

إنشاء واجهة بحث

يتطلّب إنشاء واجهة بحث بسيطة عدة خطوات:

إعداد تطبيق بحث
أنشئ بيانات اعتماد OAuth للتطبيق.
استعلم عن الفهرس.
عرض نتائج طلب البحث

يمكنك تحسين الواجهة باستخدام ميزات مثل تقسيم النتائج إلى صفحات والترتيب والفلترة والتصنيف الفرعي والإكمال التلقائي.

إعداد تطبيق بحث

يجب إنشاء تطبيق بحث واحد على الأقل لكل واجهة بحث. يوفر تطبيق البحث المعلمات التلقائية، مثل مصادر البيانات ونظام الترتيب والفلاتر والواجهات. يمكنك تجاهل هذه المَعلمات باستخدام واجهة برمجة التطبيقات Query.

لا يمكنك زيادة عدد مصادر البيانات المستخدَمة في طلب بحث بما يتجاوز تلك التي تم ضبطها في تطبيق البحث. يمكنك حصر الاستعلام على مجموعة فرعية من هذه المصادر باستخدام dataSourceRestrictions.

لمزيد من المعلومات، اطّلِع على تخصيص تجربة البحث.

إنشاء بيانات اعتماد OAuth للتطبيق

بالإضافة إلى الخطوات الواردة في ضبط إعدادات الوصول إلى Cloud Search API، عليك إنشاء بيانات اعتماد OAuth لتطبيق الويب.

استخدِم بيانات الاعتماد لطلب التفويض نيابةً عن المستخدم. استخدِم النطاق https://www.googleapis.com/auth/cloud_search.query.

لمزيد من المعلومات حول خيارات OAuth، يُرجى الاطّلاع على منصة Google Identity.

طلب البحث في الفهرس

استخدِم طريقة search للبحث في الفهرس.

يجب أن يتضمّن كل طلب نصًا query وsearchApplicationId.

يطلب هذا المثال بيانات من مصدر بيانات أفلام:

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  }
}

عرض نتائج طلب البحث

يجب أن تعرض واجهات البحث العنصر title ورابطًا يؤدي إلى العنصر الأصلي. يمكنك أيضًا استخدام المقتطفات والبيانات الوصفية لتحسين طريقة العرض.

التعامل مع النتائج الملحقة

تعرض Cloud Search نتائج تكميلية عندما لا تتوفّر نتائج مطابقة كافية لطلب بحث. يشير الحقل queryInterpretation إلى ذلك. إذا كانت النتائج الإضافية فقط هي التي يتم عرضها، تكون قيمة InterpretationType هي REPLACE. إذا كانت مدمجة، تكون BLEND.

عند عرض نتائج تكميلية، ننصحك بإعلام المستخدم بذلك. بالنسبة إلى REPLACE، يمكنك قول: "لم يتطابق بحثك مع أي نتائج. يتم عرض نتائج عن طلبات بحث مماثلة."

التعامل مع النتائج الخاصة بالأشخاص

تعرض خدمة Cloud Search مستندات ذات صلة بالأشخاص ومعلومات الموظفين باستخدام ميزة "البحث عن الأشخاص". تظهر النتائج في حقل structuredResults:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

مطابقة المرؤوسين المباشرين

تتيح ميزة "مطابقة المرؤوسين المباشرين" للمستخدمين الاطّلاع على المرؤوسين المباشرين لأحد الأشخاص. يتضمّن الردّ assistCardProtoHolder مع cardType بقيمة RELATED_PEOPLE_ANSWER_CARD.

إيقاف التحسينات

تكون التحسينات، مثل النتائج التكميلية، مفعَّلة تلقائيًا. يمكنك إيقافها باتّباع الخطوات التالية:

مستوى تطبيق البحث: اضبط force_verbatim_mode على true.
مستوى طلب البحث: اضبط enableVerbatimMode على true.

المقتطفات البارزة

تعرض Cloud Search مقتطفًا للنص أو 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 على الإزاحة المحدّدة. اضبط حجم الصفحة باستخدام pageSize. استخدِم resultCount لعرض إجمالي العناصر أو الأعداد المقدّرة.

ترتيب النتائج

استخدِم sortOptions لتحديد الترتيب:

‫operatorName: السمة التي سيتم الترتيب حسبها
sortOrder: ASCENDING أو DESCENDING

مدى الصلة بالموضوع هو مفتاح الترتيب التلقائي والثانوي.

إضافة فلاتر

يمكنك حصر النتائج باستخدام الفلاتر في تطبيق البحث أو طلب البحث. إذا حدّد كلاهما فلاتر لمصدر ما، يجب أن يتم تقييم كلاهما على أنّهما صحيحان.

تطبيق الفلاتر في dataSourceRestrictions.filterOptions[] أنواع الفلاتر الأساسية:

فلاتر العناصر: تحصر التطابقات بنوع معيّن.
فلاتر القيم: تقيّد النتائج المطابقة استنادًا إلى عامل تشغيل وقيمة.

تجمع الفلاتر المركّبة بين عدة فلاتر قيم.

تحسين النتائج باستخدام عوامل التصفية

تساعد الأوجه المستخدمين في تحسين طلبات البحث بشكل تفاعلي. عند طلب الأوجه، تحسب Cloud Search القيم الأكثر تكرارًا لهذه السمات.

النمط المعتاد: 1. طلب البحث الذي يحدّد خصائص التصنيف حسب الأوجه 1. عرض نتائج البحث ونتائج الفلاتر 1. يختار المستخدم قيم عوامل التصفية. 1. كرِّر طلب البحث باستخدام فلتر استنادًا إلى الاختيارات.

وضع علامة على سمة عدد صحيح باعتبارها قابلة للتصنيف لتنقيح النتائج حسب النطاقات (مثلاً، ‫"100-200" صفحة). اضبط isFacetable على true وحدِّد خيارات التقسيم التلقائي إلى مجموعات في المخطط.

استخدِم عوامل التشغيل المحجوزة:

‫itemsize: لحجم الملف بالبايت
‫createddatetimestamp: لتاريخ الإنشاء
lastmodified: لتاريخ التعديل

إضافة اقتراحات

استخدِم واجهة برمجة التطبيقات suggest للإكمال التلقائي استنادًا إلى سجلّ طلبات البحث وجهات الاتصال ومحتوى المستند.

إنشاء واجهة بحث باستخدام Query API