تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

ضبط تطبيق بحث

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

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

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

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

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

على سبيل المثال، لتفعيل تصفية طلبات البحث عن الأفلام حسب السنة وتقييم MPAA، يجب تضمين السمة facetOptions في طلب البحث.

"facetOptions": [
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "year"
  },
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "rated"
  }
]

يمكنك أيضًا تحديد واجهة لنتائج طلب الواجهة باستخدام حقول قائمة على عدد صحيح. على سبيل المثال، يمكنك وضع علامة على خاصية عدد صحيح تسمى book_pages كـ "facetable" لتحسين نتائج البحث عن كتب تحتوي على صفحات "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"
  }
}

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