إنشاء واجهة بحث باستخدام 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](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",
        }
      }
    }
  }]
}

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

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

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

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