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

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

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

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

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

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

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

ضبط تطبيق بحث

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

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

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

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

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

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

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

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

تمييز المقتطفات

تعرض 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 API للإكمال التلقائي استنادًا إلى سجلّ طلبات البحث وجهات الاتصال ومحتوى المستند.