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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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