إنشاء واجهة بحث باستخدام واجهة برمجة تطبيقات طلبات البحث

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

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

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

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

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

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

تهيئة تطبيق بحث

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

لمزيد من المعلومات عن تطبيقات البحث، يُرجى الرجوع إلى تخصيص تجربة البحث في Cloud Search.

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

بالإضافة إلى الخطوات الواردة في ضبط الوصول إلى واجهة برمجة تطبيقات Google Cloud Search، عليك أيضًا إنشاء بيانات اعتماد 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": {...}
  }]
}

إيقاف التحسينات، بما في ذلك النتائج التكميلية

يتم تفعيل التحسينات تلقائيًا، مثل النتائج التكميلية. يمكنك، مع ذلك، إيقاف جميع عمليات التحسين أو النتائج التكميلية فقط على كلٍّ من تطبيق البحث ومستوى طلب البحث:

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

نمط التفاعل النموذجي مع الواجهات هو:

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"
  }
}

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