إضافة الإكمال التلقائي والاقتراحات إلى تطبيقات العميل باستخدام البحث المعرفي في Azure

  • مقالة
  • قراءة خلال 8 دقائق

يعد البحث حسب النوع تقنية شائعة لتحسين إنتاجية الاستعلام. في Azure Cognitive Search، يتم دعم هذه التجربة من خلال الإكمال التلقائي، الذي ينهي مصطلحا أو عبارة تستند إلى إدخال جزئي (إكمال "micro" مع "microsoft"). تجربة المستخدم الثانية هي الاقتراحات ، أو قائمة قصيرة من المستندات المطابقة (إرجاع عناوين الكتب مع معرف بحيث يمكنك الارتباط بصفحة تفاصيل حول هذا الكتاب). يعتمد كل من الإكمال التلقائي والاقتراحات على تطابق في الفهرس. لن تقدم الخدمة استعلامات تعرض نتائج صفرية.

لتنفيذ هذه التجارب في Azure Cognitive Search، ستحتاج إلى:

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

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

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

إعداد طلب

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

POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2020-06-30
{
  "search": "minecraf",
  "suggesterName": "sg"
}

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

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

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

تكون التطابقات في بداية مصطلح في أي مكان في سلسلة الإدخال. بالنظر إلى "الثعلب البني السريع" ، سيتطابق كل من الإكمال التلقائي والاقتراحات على الإصدارات الجزئية من "the" أو "quick" أو "brown" أو "fox" ولكن ليس على مصطلحات infix الجزئية مثل "rown" أو "ox". علاوة على ذلك ، تحدد كل مباراة نطاق التوسعات النهائية. سيتطابق استعلام جزئي عن "br سريع" مع "البني السريع" أو "الخبز السريع" ، ولكن لن يتم مطابقة "البني" أو "الخبز" في حد ذاتهما ما لم يسبقهما "سريع".

واجهات برمجة التطبيقات للبحث حسب النوع

اتبع هذه الارتباطات للحصول على الصفحات المرجعية ل REST و .NET SDK:

هيكلة الاستجابة

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

تتشكل الردود من خلال المعلمات على الطلب:

  • بالنسبة إلى الإكمال التلقائي، قم بتعيين وضع الإكمال التلقائي لتحديد ما إذا كان إكمال النص يحدث على مصطلح واحد أو مصطلحين.

  • بالنسبة إلى الاقتراحات، قم بتعيين $select لإرجاع الحقول التي تحتوي على قيم فريدة أو مميزة، مثل الأسماء والوصف. تجنب الحقول التي تحتوي على قيم مكررة (مثل فئة أو مدينة).

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

المعلمة الاستخدام
البحثالحقول تقييد الاستعلام إلى حقول محددة.
‎$filter تطبيق معايير المطابقة على مجموعة النتائج ($filter=Category eq 'ActionAdventure').
$top قصر النتائج على رقم معين ($top=5).

إضافة رمز تفاعل المستخدم

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

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

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

الاقتراحات

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

بافتراض مكتبة الإكمال التلقائي لواجهة مستخدم jQuery ومشروع MVC في C # ، يمكنك تحديد مربع البحث باستخدام JavaScript في ملف Index.cshtml. تضيف المكتبة تفاعل البحث حسب النوع إلى مربع البحث عن طريق إجراء مكالمات غير متزامنة إلى وحدة تحكم MVC لاسترداد الاقتراحات.

في Index.cshtml ضمن المجلد \Views\Home، قد يكون سطر لإنشاء مربع بحث كما يلي:

<input class="searchBox" type="text" id="searchbox1" placeholder="search">

هذا المثال عبارة عن مربع نص إدخال بسيط يحتوي على فئة للتصميم ومعرف يتم الرجوع إليه بواسطة JavaScript ونص عنصر نائب.

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

$(function () {
    $("#searchbox1").autocomplete({
        source: "/home/suggest?highlights=false&fuzzy=false&",
        minLength: 3,
        position: {
            my: "left top",
            at: "left-23 bottom+10"
        }
    });
});

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

يضمن minLength: 3 عدم عرض التوصيات إلا عند وجود ثلاثة أحرف على الأقل في مربع البحث.

تمكين المطابقة الغامضة

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

source: "/home/suggest?highlights=false&fuzzy=true&",

تمكين التمييز

يطبق التمييز نمط الخط على الأحرف الموجودة في النتيجة التي تتوافق مع الإدخال. على سبيل المثال ، إذا كان الإدخال الجزئي "micro" ، فستظهر النتيجة على أنها microsoft و microscope وما إلى ذلك. يعتمد التمييز على معلمات HighlightPreTag و HighlightPostTag ، المعرفة بما يتماشى مع وظيفة الاقتراح.

source: "/home/suggest?highlights=true&fuzzy=true&",

اقتراح وظيفة

إذا كنت تستخدم C # وتطبيق MVC ، فإن ملف HomeController.cs ضمن دليل وحدات التحكم هو المكان الذي يمكنك فيه إنشاء فئة للنتائج المقترحة. في .NET، تستند الدالة Suggest إلى الأسلوب SuggestAsync. لمزيد من المعلومات حول .NET SDK، راجع كيفية استخدام البحث المعرفي Azure من تطبيق .NET.

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

بالنسبة للإكمال التلقائي، تقتصر المطابقة الغامضة على مسافة تحرير واحدة (حرف واحد محذوف أو في غير محله). لاحظ أن المطابقة الغامضة في استعلامات الإكمال التلقائي يمكن أن تؤدي في بعض الأحيان إلى نتائج غير متوقعة اعتمادا على حجم الفهرس وكيفية تقطيعه. لمزيد من المعلومات، راجع مفاهيم التقسيم والتقسيم.

public async Task<ActionResult> SuggestAsync(bool highlights, bool fuzzy, string term)
{
    InitSearch();

    var options = new SuggestOptions()
    {
        UseFuzzyMatching = fuzzy,
        Size = 8,
    };

    if (highlights)
    {
        options.HighlightPreTag = "<b>";
        options.HighlightPostTag = "</b>";
    }

    // Only one suggester can be specified per index.
    // The suggester for the Hotels index enables autocomplete/suggestions on the HotelName field only.
    // During indexing, HotelNames are indexed in patterns that support autocomplete and suggested results.
    var suggestResult = await _searchClient.SuggestAsync<Hotel>(term, "sg", options).ConfigureAwait(false);

    // Convert the suggest query results to a list that can be displayed in the client.
    List<string> suggestions = suggestResult.Value.Results.Select(x => x.Text).ToList();

    // Return the list of suggestions.
    return new JsonResult(suggestions);
}

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

الإكمال التلقائي

حتى الآن ، تم تركيز رمز UX للبحث على الاقتراحات. تعرض كتلة التعليمات البرمجية التالية الإكمال التلقائي، باستخدام وظيفة الإكمال التلقائي لواجهة مستخدم XDSoft jQuery، التي يتم تمريرها في طلب الإكمال التلقائي للبحث المعرفي في Azure. كما هو الحال مع الاقتراحات ، في تطبيق C # ، يتم إرسال التعليمات البرمجية التي تدعم تفاعل المستخدم في index.cshtml.

$(function () {
    // using modified jQuery Autocomplete plugin v1.2.8 https://xdsoft.net/jqplugins/autocomplete/
    // $.autocomplete -> $.autocompleteInline
    $("#searchbox1").autocompleteInline({
        appendMethod: "replace",
        source: [
            function (text, add) {
                if (!text) {
                    return;
                }

                $.getJSON("/home/autocomplete?term=" + text, function (data) {
                    if (data && data.length > 0) {
                        currentSuggestion2 = data[0];
                        add(data);
                    }
                });
            }
        ]
    });

    // complete on TAB and clear on ESC
    $("#searchbox1").keydown(function (evt) {
        if (evt.keyCode === 9 /* TAB */ && currentSuggestion2) {
            $("#searchbox1").val(currentSuggestion2);
            return false;
        } else if (evt.keyCode === 27 /* ESC */) {
            currentSuggestion2 = "";
            $("#searchbox1").val("");
        }
    });
});

وظيفة الإكمال التلقائي

يعتمد الإكمال التلقائي على طريقة الإكمال التلقائيAsync. كما هو الحال مع الاقتراحات ، ستنتقل كتلة التعليمات البرمجية هذه إلى ملف HomeController.cs .

public async Task<ActionResult> AutoCompleteAsync(string term)
{
    InitSearch();

    // Setup the autocomplete parameters.
    var ap = new AutocompleteOptions()
    {
        Mode = AutocompleteMode.OneTermWithContext,
        Size = 6
    };
    var autocompleteResult = await _searchClient.AutocompleteAsync(term, "sg", ap).ConfigureAwait(false);

    // Convert the autocompleteResult results to a list that can be displayed in the client.
    List<string> autocomplete = autocompleteResult.Value.Results.Select(x => x.Text).ToList();

    return new JsonResult(autocomplete);
}

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

الخطوات التالية

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