الترقية إلى Azure Cognitive Search .NET SDK الإصدار 11

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

إذا كان حل البحث الخاص بك مبنيا على Azure SDK ل .NET، فستساعدك هذه المقالة على ترحيل التعليمات البرمجية من الإصدارات السابقة من Microsoft.Azure.Search إلى الإصدار 11، مكتبة عميل Azure.Search.Documents الجديدة. الإصدار 11 عبارة عن مكتبة عملاء أعيد تصميمها بالكامل، تم إصدارها بواسطة فريق تطوير Azure SDK (تم إنتاج الإصدارات السابقة بواسطة فريق تطوير البحث المعرفي في Azure).

يتم تنفيذ جميع الميزات من الإصدار 10 في الإصدار 11. تشمل الاختلافات الرئيسية ما يلي:

  • حزمة واحدة (Azure.Search.Documents) بدلا من أربعة
  • ثلاثة عملاء بدلا من اثنين: SearchClient، SearchIndexClient، SearchIndexerClient
  • اختلافات التسمية عبر مجموعة من واجهات برمجة التطبيقات والاختلافات الهيكلية الصغيرة التي تبسط بعض المهام

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

تمت مراجعة كافة نماذج التعليمات البرمجية ل C # والمقتطفات في وثائق منتج البحث المعرفي لاستخدام مكتبة عميل Azure.Search.Documents الجديدة.

لماذا الترقية؟

وتتلخص فوائد الترقية فيما يلي:

  • ستتم إضافة ميزات جديدة إلى Azure.Search.Documents فقط. الإصدار السابق ، Microsoft.Azure.Search ، متقاعد الآن. تقتصر تحديثات المكتبات المهملة على إصلاحات الأخطاء ذات الأولوية العالية فقط.

  • الاتساق مع مكتبات عملاء Azure الأخرى. يعتمد Azure.Search.Documents على Azure.CoreوSystem.Text.Json، ويتبع الأساليب التقليدية للمهام الشائعة مثل اتصالات العميل والتفويض.

مقارنة الحزم

يعمل الإصدار 11 على دمج وتبسيط إدارة الحزم بحيث يكون هناك عدد أقل للإدارة.

الإصدار 10 والإصدارات الأقدم الإصدار 11
Microsoft.Azure.Search
Microsoft.Azure.Search.Service
Microsoft.Azure.Search.Data
Microsoft.Azure.Search.Common		 حزمة Azure.Search.Documents

مقارنة العملاء

حيثما ينطبق ذلك، يقوم الجدول التالي بتعيين مكتبات العميل بين الإصدارين.

عمليات العميل Microsoft.Azure.Search (v10) Azure.Search.Documents (v11)
يستهدف جمع المستندات الخاصة بفهرس (الاستعلامات واستيراد البيانات) SearchIndexClient عميل البحث
استهداف الكائنات ذات الصلة بالفهرس (الفهارس، وأجهزة التحليل، وخرائط المرادفات خدمة البحثالعميلالعميل SearchIndexClient
استهداف الكائنات ذات الصلة بالمفهرس (المفهرسات، مصادر البيانات، مجموعات المهارات) خدمة البحثالعميلالعميل SearchIndexerClient (جديد)

تنبيه

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

التسمية والاختلافات الأخرى في واجهة برمجة التطبيقات

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

المصادقة والتشفير

الإصدار 10 ما يعادل الإصدار 11
البحثبيانات الاعتماد AzureKeyCredential
مفتاح التشفير (غير موثق في مرجع واجهة برمجة التطبيقات. تم نقل دعم واجهة برمجة التطبيقات هذه إلى متوفر بشكل عام في الإصدار 10 ، ولكنه كان متاحا فقط في مجموعة SDK للمعاينة) SearchResourceEncryptionKey

الفهارس والمحللات وخرائط المرادفات

الإصدار 10 ما يعادل الإصدار 11
الفهرس فهرس البحث
الحقل حقل البحث
نوع البيانات SearchFieldDataType
ItemError SearchIndexerError
المحلل LexicalAnalyzer (أيضا ، AnalyzerName إلى LexicalAnalyzerName)
تحليلطلب AnalyzeTextOptions
ستاندرد أنالايزر LuceneStandardAnalyzer
StandardTokenizer LuceneStandardTokenizer (أيضا ، StandardTokenizerV2 إلى LuceneStandardTokenizerV2)
توكنينفو AnalyzedTokenInfo
الرمز المميز LexicalTokenizer (أيضا ، TokenizerName إلى LexicalTokenizerName)
SynonymMap.Format لا شيء إزالة الإشارات إلى Format.

يتم تبسيط تعريفات الحقول: SearchableField و SimpleField و ComplexField هي واجهات برمجة تطبيقات جديدة لإنشاء تعريفات الحقول.

المفهرسات ومصادر البيانات ومجموعات المهارات

الإصدار 10 ما يعادل الإصدار 11
المُفهرس SearchIndexer
DataSource SearchIndexerDataSourceConnection
المهارة SearchIndexerSkill
مجموعة المهارات SearchIndexerSkillset
داتا سورس تايب SearchIndexerDataSourceType

استيراد البيانات

الإصدار 10 ما يعادل الإصدار 11
IndexAction فهرسالوثائقالعمل
إندكسباتش فهرسالمستنداتدفعة
IndexBatchException.FindFailedActionsToRetry() SearchIndexingBufferedSender

طلبات الاستعلام والردود

الإصدار 10 ما يعادل الإصدار 11
DocumentsOperationsExtensions.SearchAsync SearchClient.SearchAsync
DocumentSearchResult SearchResult أو SearchResults، اعتمادا على ما إذا كانت النتيجة مستندا واحدا أو متعددا.
DocumentSuggestResult اقتراحالنتائج
معلمات البحث خيارات البحث
اقتراحالمعلمات اقتراحخيارات
SearchParameters.Filter SearchFilter (فئة جديدة لإنشاء تعبيرات عامل تصفية OData)

تسلسل JSON

بشكل افتراضي، يستخدم Azure SDK System.Text.Json لتسلسل JSON ، معتمدا على قدرات واجهات برمجة التطبيقات هذه للتعامل مع تحويلات النص التي تم تنفيذها مسبقا من خلال فئة SerializePropertyNamesAsCamelCaseAttribute الأصلية، والتي ليس لها نظير في المكتبة الجديدة.

لتسلسل أسماء الخصائص في camelCase، يمكنك استخدام السمة JsonPropertyNameAttribute (على غرار هذا المثال).

بدلا من ذلك، يمكنك تعيين JsonNamingPolicy المتوفر في JsonSerializerOptions. يوضح مثال التعليمات البرمجية System.Text.Json التالي، المأخوذ من الملف التمهيدي Microsoft.Azure.Core.Spatial، استخدام camelCase دون الحاجة إلى إسناد كل خاصية:

// Get the Azure Cognitive Search endpoint and read-only API key.
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));

// Create serializer options with our converter to deserialize geographic points.
JsonSerializerOptions serializerOptions = new JsonSerializerOptions
{
    Converters =
    {
        new MicrosoftSpatialGeoJsonConverter()
    },
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

SearchClientOptions clientOptions = new SearchClientOptions
{
    Serializer = new JsonObjectSerializer(serializerOptions)
};

SearchClient client = new SearchClient(endpoint, "mountains", credential, clientOptions);
Response<SearchResults<Mountain>> results = client.Search<Mountain>("Rainier");

إذا كنت تستخدم Newtonsoft.Json لتسلسل JSON، فيمكنك تمرير نهج التسمية العمومية باستخدام سمات مماثلة، أو باستخدام الخصائص الموجودة على JsonSerializerSettings. للحصول على مثال مكافئ للمثال أعلاه، راجع مثال إزالة تسلسل المستندات في الملف التمهيدي Newtonsoft.Json.

داخل v11

يستهدف كل إصدار من مكتبة عميل Azure Cognitive Search إصدارا مطابقا من واجهة برمجة تطبيقات REST. تعتبر واجهة برمجة تطبيقات REST أساسية للخدمة ، حيث تقوم مجموعات SDK الفردية بتغليف إصدار من واجهة برمجة تطبيقات REST. بصفتك مطور .NET ، قد يكون من المفيد مراجعة وثائق واجهة برمجة تطبيقات REST الأكثر إسهابا للحصول على تغطية أكثر تعمقا لكائنات أو عمليات محددة. يستهدف الإصدار 11 خدمة البحث 2020-06-30.

يدعم الإصدار 11.0 بشكل كامل الكائنات والعمليات التالية:

  • إنشاء وإدارة المؤشرات
  • إنشاء خريطة مرادفة وإدارتها
  • إنشاء المفهرس وإدارته
  • إنشاء وإدارة مصادر بيانات المفهرس
  • إنشاء وإدارة مجموعة المهارات
  • جميع أنواع الاستعلام وبناء الجملة

إضافات الإصدار 11.1 (تغيير تفاصيل السجل ):

إضافات الإصدار 11.2 (تغيير تفاصيل السجل ):

إضافات الإصدار 11.3 (تغيير تفاصيل السجل ):

قبل الترقية

  • تم تحديث عمليات التشغيل السريع والبرامج التعليمية وعينات C#‎ لاستخدام حزمة Azure.Search.Documents. نوصي بمراجعة العينات والإرشادات التفصيلية للتعرف على واجهات برمجة التطبيقات الجديدة قبل الشروع في عملية الترحيل.

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

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

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

  1. قم بتثبيت حزمة Azure.Search.Documents بالنقر بزر الماوس الأيمن فوق مراجع المشروع وتحديد "إدارة حزم NuGet ..." في Visual Studio.

  2. استبدل استخدام التوجيهات الخاصة ب Microsoft.Azure.Search بما يلي:

    using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

  3. بالنسبة للفئات التي تتطلب تسلسل JSON، استبدلها using Newtonsoft.Json ب using System.Text.Json.Serialization.

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

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

    Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);

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

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

    var options = new SearchOptions
 {
    SearchMode = SearchMode.All,
    IncludeTotalCount = true
 };

 // Select fields to return in results.
 options.Select.Add("HotelName");
 options.Select.Add("Description");
 options.Select.Add("Tags");
 options.Select.Add("Rooms");
 options.Select.Add("Rating");
 options.Select.Add("LastRenovationDate");

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

  7. تحديث مراجع العميل للاستعلامات واستيراد البيانات. يجب تغيير مثيلات SearchIndexClient إلى SearchClient. لتجنب الارتباك في الأسماء، تأكد من التقاط جميع المثيلات قبل المتابعة إلى الخطوة التالية.

  8. تحديث مراجع العميل للفهرس وخريطة المرادفات وكائنات المحلل. يجب تغيير مثيلات SearchServiceClient إلى SearchIndexClient.

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

    إذا كنت تواجه مشكلة في العثور على https://github.com/MicrosoftDocs/azure-docs/issues واجهات برمجة التطبيقات المكافئة، فإننا نقترح تسجيل مشكلة حتى نتمكن من تحسين الوثائق أو التحقيق في المشكلة.

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

التغييرات الطارئة

نظرا للتغييرات الشاملة التي طرأت على المكتبات وواجهات برمجة التطبيقات ، فإن الترقية إلى الإصدار 11 ليست تافهة وتشكل تغييرا جذريا بمعنى أن التعليمات البرمجية الخاصة بك لن تكون متوافقة مع الإصدار 10 والإصدارات الأقدم. للحصول على مراجعة شاملة للاختلافات، راجع سجل التغيير الخاص ب Azure.Search.Documents.

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

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

  • تغيرت النتائج المرتبة للقيم الخالية في هذا الإصدار، مع ظهور القيم الخالية أولا إذا كان الفرز والأخير asc إذا كان الفرز .desc إذا كتبت تعليمة برمجية للتعامل مع كيفية فرز القيم الفارغة، فيجب عليك مراجعة هذه التعليمة البرمجية وإزالتها إذا لم تعد ضرورية.

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