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

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

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

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

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

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

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

ضبط تطبيق بحث

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

لمزيد من المعلومات عن تطبيقات البحث، يُرجى الرجوع إلى مقالة تخصيص تجربة البحث في 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 لتحديد المعرّف الذي يستخدمه تطبيق البحث.

يعرض المقتطف التالي طلب بحث موجَّه إلى مصدر بيانات الفيلم "تايتانيك":

{
  "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. كلّ سطر وصفي هو مصفوفة من تصنيفات العرض و pairings value كما تم ضبطها في المخطّط.

استرداد نتائج إضافية

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

نمط التفاعل المعتاد مع السمات هو:

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

على سبيل المثال، لتفعيل تحسين طلبات البحث عن الأفلام حسب السنة وتقييم جمعية الفيلم الأمريكي (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"
  }
}

ويمكنك بعد ذلك عرض الاقتراحات الناتجة حسب ما يناسب تطبيقك.