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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

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

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

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

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

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

بالإضافة إلى الخطوات الواردة في إعداد الوصول إلى واجهة برمجة تطبيقات REST في Google Cloud Search، عليك أيضًا إنشاء بيانات اعتماد OAuth لتطبيق الويب. ويعتمد نوع بيانات الاعتماد التي تنشئها على السياق الذي يتم فيه استخدام واجهة برمجة التطبيقات.

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

لمزيد من المعلومات عن خيارات OAuth ومكتبات العميل، يمكنك الاطّلاع على {0}منصة Google Identity](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": {...}
  }]
}

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

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

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

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

الفلاتر المركَّبة تتيح دمج فلاتر متعددة القيم في تعبيرات منطقية لطلبات بحث أكثر تعقيدًا.

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

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

تفسير مجموعات بيانات الواجهات

تتضمّن الخاصية facetResults في الاستجابة إدخالاً لكل سمة مطلوبة. ولكل موقع، يتم توفير قائمة من القيم أو النطاقات تسمى buckets. تظهر القيم الأكثر تكرارًا أولاً.

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

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

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

على سبيل المثال، تقدّم المكالمة التالية اقتراحات للعبارة الجزئية jo.

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

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