Share via

Frissítés az Azure AI Search .NET SDK 11-es verziójára

  • Cikk

Ha a keresési megoldás a .NET-hez készült Azure SDK-ra épül, ez a cikk segít áttelepíteni a kódot a Microsoft.Azure.Search korábbi verzióiból a 11-es verzióra, az új Azure.Search.Documents ügyfélkódtárba. A 11-es verzió egy teljesen újratervezett ügyfélkódtár, amelyet az Azure SDK fejlesztői csapata bocsátott ki (a korábbi verziókat az Azure AI Search fejlesztői csapata állította elő).

A 10-es verzió összes funkciója a 11-es verzióban van implementálva. A főbb különbségek a következők:

  • Négy helyett egy csomag (Azure.Search.Documents)
  • Kettő helyett három ügyfél: SearchClient, SearchIndexClient, SearchIndexerClient
  • Különböző API-k elnevezése és kisebb szerkezeti különbségek, amelyek leegyszerűsítenek bizonyos feladatokat

Az ügyfélkódtár változásnaplója a frissítések tételes listáját tartalmazza. Ebben a cikkben áttekintheti az összegzett verziót .

Az Azure AI Search termékdokumentációjában szereplő összes C#-kódmintát és kódrészletet átdolgoztuk az új Azure.Search.Documents ügyfélkódtár használatára.

Miért érdemes frissíteni?

A frissítés előnyei az alábbiak szerint vannak összefoglalva:

  • Az új funkciók csak az Azure.Search.Documents szolgáltatáshoz lesznek hozzáadva. Az előző verzió, a Microsoft.Azure.Search ki lett állítva. Frissítések elavult kódtárak csak a magas prioritású hibajavításokra korlátozódnak.

  • Konzisztencia más Azure-ügyfélkódtárakkal. Az Azure.Search.Documents függőséget alkalmaz az Azure.Core és a System.Text.Json szolgáltatásban, és a hagyományos megközelítéseket követi az olyan gyakori feladatokhoz, mint az ügyfélkapcsolatok és az engedélyezés.

A Microsoft.Azure.Search hivatalosan ki van állítva. Ha régi verziót használ, javasoljuk, hogy frissítsen a következő magasabb verzióra, és ismételje meg a folyamatot egymás után, amíg el nem éri a 11-es és az Azure.Search.Documents verziót. A növekményes frissítési stratégia megkönnyíti a blokkolási problémák megtalálását és kijavítását. Útmutatásért tekintse meg az előző verzió dokumentumait .

Csomag összehasonlítása

A 11-es verzió összevonja és leegyszerűsíti a csomagkezelést, így kevesebb kezelhetőség érhető el.

10-es és korábbi verzió 11-es verzió
Microsoft.Azure.Search Microsoft.Azure.Search.Service
Microsoft.Azure.Search.Data
Microsoft.Azure.Search.Common
 Azure.Search.Documents csomag

Ügyfél-összehasonlítás

Adott esetben az alábbi táblázat leképezi az ügyfélkódtárakat a két verzió között.

Ügyfélműveletek Microsoft.Azure.Search (v10) Azure.Search.Documents (v11)
Egy index dokumentumgyűjteményét célozza meg (lekérdezések és adatimportálás) SearchIndexClient SearchClient
Indexel kapcsolatos objektumokat (indexeket, elemzőket, szinonimatérképeket) céloz meg SearchServiceClient SearchIndexClient
Indexelővel kapcsolatos objektumok (indexelők, adatforrások, képességkészletek) célba szerzése SearchServiceClient SearchIndexerClient (új)

Figyelmeztetés

Figyelje meg, hogy a SearchIndexClient mindkét verzióban létezik, de különböző műveleteket céloz meg. A 10-es verzióban a SearchIndexClient indexeket és egyéb objektumokat hoz létre. A 11-es verzióban a SearchIndexClient a meglévő indexekkel működik, és a dokumentumgyűjteményt lekérdezési és adatbetöltési API-kkal célozza meg. A kód frissítésekor történő félreértések elkerülése érdekében vegye figyelembe az ügyfélhivatkozások frissítésének sorrendjét. A frissítési lépések sorozatának követésével enyhítheti a sztringek cseréjével kapcsolatos problémákat.

Elnevezés és egyéb API-különbségek

Az ügyféleltéréseken kívül (amelyeket korábban már említettünk, és így itt kihagytunk) több más API-t is átneveztek, és egyes esetekben újratervezték. Az osztálynév-különbségeket a következő szakaszokban összegezzük. Ez a lista nem teljes, de feladatonként csoportosítja az API-módosításokat, ami hasznos lehet adott kódblokkok változatainak esetében. Az API-frissítések tételes listájáért tekintse meg a GitHub változásnaplójátAzure.Search.Documents.

Hitelesítés és titkosítás

10-es verzió A 11-es verzió megfelelője
Keresési hitelesítő adatok AzureKeyCredential
EncryptionKey (AZ API-referencia nem dokumentált. Ennek az API-nak a támogatása a 10-es verzióban általánosan elérhetőre váltott, de csak az előzetes verziójú SDK-ban volt elérhető) SearchResourceEncryptionKey

Indexek, elemzők, szinonimák térképei

10-es verzió A 11-es verzió megfelelője
Index SearchIndex
Mező SearchField
Adattípus SearchFieldDataType
ItemError SearchIndexerError
Elemző LexicalAnalyzer (is, AnalyzerName a LexicalAnalyzerName)
AnalyzeRequest AnalyzeTextOptions
StandardAnalyzer LuceneStandardAnalyzer
StandardTokenizer LuceneStandardTokenizer (is, StandardTokenizerV2 a LuceneStandardTokenizerV2)
TokenInfo AnalyzedTokenInfo
Tokenizer LexikálisTokenizer (is, TokenizerName hogy LexicalTokenizerName)
Szinonimatérkép.Format Nincs. A hivatkozás eltávolítása.Format

A meződefiníciók egyszerűbbek: a SearchableField, a SimpleField és a ComplexField új API-k a meződefiníciók létrehozásához.

Indexelők, adatforrások, készségkészletek

10-es verzió A 11-es verzió megfelelője
Indexelő SearchIndexer
Datasource SearchIndexerDataSource Csatlakozás ion
Ügyességi SearchIndexerSkill
Skillset SearchIndexerSkillset
DataSourceType SearchIndexerDataSourceType

Adatimportálás

10-es verzió A 11-es verzió megfelelője
IndexAction IndexDocumentsAction
IndexBatch IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry() SearchIndexingBufferedSender

Lekérdezési kérelmek és válaszok

10-es verzió A 11-es verzió megfelelője
DocumentsOperationsExtensions.SearchAsync SearchClient.SearchAsync
DocumentSearchResult SearchResult vagy SearchResults, attól függően, hogy az eredmény egy dokumentum vagy több.
DocumentSuggestResult SuggestResults
SearchParameters SearchOptions
SuggestParameters SuggestOptions
SearchParameters.Filter SearchFilter (új osztály OData-szűrőkifejezések létrehozásához)

JSON-szerializálás

Az Azure SDK alapértelmezés szerint System.Text.Json-t használ JSON-szerializáláshoz, és ezen API-k képességeire támaszkodva kezeli a korábban natív SerializePropertyNamesAsCamelCaseAttribute osztályon keresztül végrehajtott szövegátalakításokat, amelyeknek nincs megfelelője az új kódtárban.

A tulajdonságnevek camelCase-be való szerializálásához használhatja a JsonPropertyNameAttribute parancsot (a példához hasonlóan).

Másik lehetőségként beállíthatja a JsonSerializerOptionsban megadott JsonNamingPolicy-t. A Microsoft.Azure.Core.Spatial readme-ből vett következő System.Text.Json-kód példa a CamelCase használatát mutatja be anélkül, hogy minden tulajdonságot attribútummal kellene ellátnia:

// Get the Azure AI Search service 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");

Ha Newtonsoft.Json-t használ JSON-szerializáláshoz, a globális elnevezési szabályzatokat hasonló attribútumokkal, vagy a JsonSerializer tulajdonságainak használatával is átadhatja Gépház. Az előzőnek megfelelő példáért tekintse meg a Dokumentumok deszerializálása című példát a Newtonsoft.Json-olvasóban.

11-ben

Az Azure AI Search-ügyfélkódtár minden verziója a REST API megfelelő verzióját célozza meg. A REST API a szolgáltatás alapja, az egyes SDK-k pedig a REST API egy verzióját burkolják. .NET-fejlesztőként hasznos lehet áttekinteni a részletesebb REST API-dokumentációt , hogy részletesebben le tudja fedni az adott objektumokat vagy műveleteket. A 11-es verzió a 2020-06-30 keresési szolgáltatás specifikációját célozza.

A 11.0-s verzió teljes mértékben támogatja a következő objektumokat és műveleteket:

  • Index létrehozása és kezelése
  • Szinonimák leképezésének létrehozása és kezelése
  • Indexelő létrehozása és kezelése
  • Indexelő adatforrás létrehozása és kezelése
  • Képességkészlet létrehozása és kezelése
  • Minden lekérdezéstípus és szintaxis

11.1-es verziójú kiegészítések (változásnapló részletei):

A 11.2-es verzió kiegészítései (a napló részleteinek módosítása):

11.3-es verziójú kiegészítések (változásnapló részletei):

Frissítés előtt

  • Rövid útmutatók, oktatóanyagok és C#-minták frissültek az Azure.Search.Documents csomag használatához. Javasoljuk, hogy a migrálási gyakorlat megkezdése előtt tekintse át a mintákat és az útmutatókat az új API-k megismeréséhez.

  • Az Azure.Search.Documents használata a leggyakrabban használt API-kat mutatja be. Még az Azure AI Search tájékozott felhasználói is érdemes lehet áttekinteni ezt a bevezetést az új kódtárban a migrálás elődjeként.

A frissítés lépései

Az alábbi lépések a kódmigrálás első lépéseit követve végigvezetik a szükséges feladatok első készletén, különösen az ügyfélhivatkozások tekintetében.

  1. Telepítse az Azure.Search.Documents csomagot a jobb gombbal a projekthivatkozásokra kattintva, majd válassza a "NuGet-csomagok kezelése..." lehetőséget. a Visual Studióban.

  2. Cserélje le a Microsoft.Azure.Search irányelveit a következő utasításokra:

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

  3. JSON-szerializálást igénylő osztályok esetén cserélje le using Newtonsoft.Json a következőre using System.Text.Json.Serialization: .

  4. Ügyfél-hitelesítési kód módosítása. A korábbi verziókban az ügyfélobjektum tulajdonságaival állíthatja be az API-kulcsot (például a SearchServiceClient.Credentials tulajdonságot ). Az aktuális verzióban az AzureKeyCredential osztály használatával adja át a kulcsot hitelesítő adatként, így szükség esetén új ügyfélobjektumok létrehozása nélkül frissítheti az API-kulcsot.

    Az ügyféltulajdonságok egyszerűen Endpoint, ServiceNameés IndexName (adott esetben) egyszerűbbé lettek. Az alábbi példa a system Uri osztályt használja a végpont és a Környezeti osztály beolvasásához a kulcsértékben:

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

  5. Új ügyfélhivatkozások hozzáadása indexelővel kapcsolatos objektumokhoz. Ha indexelőket, adatforrásokat vagy képességkészleteket használ, módosítsa az ügyfélhivatkozásokat a SearchIndexerClientre. Ez az ügyfél a 11-es verzióban új, és nincs előzménye.

  6. Gyűjtemények és listák felülvizsgálata. Az új SDK-ban minden lista írásvédett, így elkerülhetők az alsóbb rétegbeli problémák, ha a lista null értékeket tartalmaz. A kód módosítása az, hogy elemeket ad hozzá egy listához. Például ahelyett, hogy sztringeket rendelne egy Select tulajdonsághoz, a következőképpen adja hozzá őket:

    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");

    A Select, a Facets, a SearchFields, a SourceFields, a ScoringParameters és az OrderBy mind olyan listák, amelyeket most rekonstruálni kell.

  7. Lekérdezések és adatimportálás ügyfélhivatkozásainak frissítése. A SearchIndexClient példányait SearchClientre kell módosítani. A névelkontúllépés elkerülése érdekében minden példányt el kell kapnia, mielőtt továbblépne a következő lépésre.

  8. Index-, szinonimatérkép- és elemzőobjektumok ügyfélhivatkozásainak frissítése. A SearchServiceClient példányait SearchIndexClientre kell módosítani.

  9. A kód fennmaradó részében frissítse az osztályokat, metódusokat és tulajdonságokat az új kódtár API-jainak használatára. Az elnevezési különbségek szakaszt érdemes elkezdeni, de a változásnaplót is áttekintheti.

    Ha nem találja a megfelelő API-kat, javasoljuk, hogy jelentkezzen be a problémába https://github.com/MicrosoftDocs/azure-docs/issues , hogy javíthassuk a dokumentációt, vagy kivizsgálhassuk a problémát.

  10. A megoldás újraépítése. A buildelési hibák vagy figyelmeztetések kijavítása után további módosításokat végezhet az alkalmazáson az új funkciók előnyeinek kihasználásához.

Kompatibilitástörő változások

Tekintettel a kódtárak és API-k jelentős változásaira, a 11-es verzióra való frissítés nem triviális, és kompatibilitástörő változást jelent abban az értelemben, hogy a kód többé nem lesz kompatibilis a 10-es és korábbi verzióval. A különbségek alapos áttekintéséhez tekintse meg a változásnaplótAzure.Search.Documents.

A szolgáltatásverzió-frissítések tekintetében, ahol a 11-es verzió kódváltozásai a meglévő funkciókhoz kapcsolódnak (és nem csak az API-k újrabontásához), a következő viselkedésbeli változások találhatók:

  • A BM25 rangsorolási algoritmus az előző rangsorolási algoritmust újabb technológiára cseréli. Az új szolgáltatások automatikusan használják ezt az algoritmust. Meglévő szolgáltatások esetén paramétereket kell beállítania az új algoritmus használatához.

  • A null értékek rendezett eredményei megváltoztak ebben a verzióban, és a null értékek jelennek meg először, ha a rendezés és asc az utolsó, ha a rendezés.desc Ha a null értékek rendezésének kezelésére kódot írt, érdemes áttekinteni és esetlegesen eltávolítani a kódot, ha már nincs rá szükség.

Ezeknek a viselkedésbeli változásoknak köszönhetően valószínű, hogy a rangsorolt eredmények kismértékben változnak.

Következő lépések