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

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

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

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

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

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

مطابقة التقارير المباشرة

"مطابقة التقارير المباشرة" هي ميزة في "البحث عن الأشخاص" في 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",
        }
      }
    }
  }]
}

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

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

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

بالنسبة إلى السلع المعروضة التي تحتوي على نص مفهرس أو محتوى 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"
  }
}

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