Oktatóanyag: Azure SQL adatok indexelése a .NET SDK használatával

Megtudhatja, hogyan konfigurálhat egy indexert a kereshető adatok kinyeréséhez az Azure SQL Database-ből, és hogyan küldheti el azokat egy keresési indexbe az Azure AI Keresés-ben.

Ebben az oktatóanyagban a C# és a Azure SDK-t .NET-hez a következő célokra használja:

Előfeltételek

• Aktív előfizetéssel rendelkező Azure fiók. Fiók létrehozása ingyenesen.
• Azure SQL Database SQL Server hitelesítéssel.
• Azure AI Keresés. Szolgáltatás létrehozása vagy meglévő szolgáltatás definiálása az aktuális előfizetésben.
• Visual Studio.

Fájlok letöltése

Az oktatóanyag forráskódja a DotNetHowToIndexer mappában található a Azure-Samples/search-dotnet-getting-started GitHub adattárban.

Szolgáltatások létrehozása

Ez az oktatóanyag az Azure AI Keresés-öt használja az indexeléshez és lekérdezésekhez, valamint az Azure SQL Database-t külső adatforrásként. Ha lehetséges, hozzon létre mindkét szolgáltatást ugyanabban a régióban és erőforráscsoportban a közelség és a kezelhetőség érdekében. A gyakorlatban az Azure SQL Database bármely régióban lehet.

Kezdje az Azure SQL Database alkalmazással

Ez az oktatóanyag a hotels.sql fájlt tartalmazza a mintaletöltésben az adatbázis feltöltéséhez. Azure AI Keresés egybesimított sorhalmazokat használ, például egy nézetből vagy lekérdezésből létrehozottat. A minta megoldásban található SQL-fájl egyetlen táblát hoz létre és tölt fel.

Ha már rendelkezik Azure SQL Database erőforrásával, a szállodatáblát a Előkérdezés lépéstől kezdve veheti fel.

1. A Azure SQL database létrehozása. Az adatbázis kiszolgálókonfigurációja fontos:

   • Válassza a SQL Server hitelesítési lehetőséget, amely a felhasználónév és a jelszó megadását kéri. Az indexelő által használt ADO.NET kapcsolati karakterláncra van szüksége.

   • Válasszon nyilvános kapcsolatot, amely megkönnyíti ezt az oktatóanyagot. A nyilvános verzió nem ajánlott éles használatra, és azt javasoljuk, hogy az oktatóanyag végén törölje ezt az erőforrást.

   

2. Az Azure portálon navigáljon az új erőforráshoz.

3. Adjon hozzá egy tűzfalszabályt, amely lehetővé teszi a hozzáférést az ügyfélnek. A parancssorból futtatva ipconfig lekérheti az IP-címét.

4. A mintaadatok betöltéséhez használja a Query editor. A navigációs panelen válassza a Query editor (előzetes verzió) lehetőséget, és adja meg a kiszolgáló rendszergazdájának felhasználónevét és jelszavát.

   Ha „hozzáférés megtagadva” hibaüzenetet kap, másolja ki az ügyfél IP-címét a hibaüzenetből, nyissa meg a kiszolgáló hálózati biztonsági oldalát, és adjon hozzá egy bejövő szabályt, amely lehetővé teszi a hozzáférést az ügyféltől.

5. A Query editorban válassza a Lekérdezés megnyitása lehetőséget, és keresse meg a helyi számítógépen található hotels.sql fájl helyét.

6. Jelölje ki a fájlt, és válassza a Megnyitás lehetőséget. A szkriptnek az alábbi képernyőfelvételhez hasonlóan kell kinéznie:

   

7. Válassza a Futtatás lehetőséget a lekérdezés végrehajtásához. Az Eredmények panelen egy lekérdezés sikeres üzenetének kell megjelennie három sorra vonatkozóan.

8. A jelen táblából származó sorhalmaz visszaadásához hajtsa végre a következő lekérdezést ellenőrzési lépésként:

   SELECT * FROM Hotels
   

9. Másolja ki az ADO.NET kapcsolat stringet az adatbázishoz. A Settings>Connection Strings területen másolja ki az ADO.NET kapcsolati karakterlánc, amely az alábbi példához hasonló:

   Server=tcp:<YOUR-DATABASE-NAME>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<YOUR-USER-NAME>;Password=<YOUR-PASSWORD>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;
   

A következő lépésben szüksége lesz erre a kapcsolati karakterláncre a környezet beállításához.

Azure AI Keresés

A következő összetevő a Azure AI Keresés, amelyet a Azure portal hozhat létre. Az oktatóanyag elvégzéséhez használhatja az ingyenes szintet.

Rendszergazdai kulcs és URL-cím lekérése Azure AI Keresés

Az API-hívásokhoz a szolgáltatás URL-címe és egy access kulcs szükséges. Mindkettővel létrejön egy search service, ezért ha Azure AI Keresés adott hozzá az előfizetéshez, a szükséges információk beszerzéséhez kövesse az alábbi lépéseket:

1. Nyissa meg a keresési szolgáltatást az Azure Portalon.

2. Az Áttekintés lapon másolja ki a végpont URL-címét. Például egy végpont https://mydemo.search.windows.net.

3. ABeállításkulcsok> lapon szerezze be a szolgáltatás teljes jogosultságainak rendszergazdai kulcsát. Két felcserélhető rendszergazdai kulcs áll rendelkezésre az üzletmenet folytonossága érdekében, ha át kell gördítenie egyet. Az objektumok hozzáadásához, módosításához vagy törléséhez a kérelmek egyik kulcsát használhatja.

   

Saját környezet beállítása

1. Indítsa el Visual Studio, és nyissa meg a DotNetHowToIndexers.sln.

2. A Megoldáskezelő nyissa meg a appsettings.json a kapcsolati adatok megadásához.

3. Ha SearchServiceEndPoint esetén a szolgáltatás teljes URL-címe Overview oldal https://my-demo-service.search.windows.net, adja meg a teljes URL-címet.

4. A AzureSqlConnectionString esetében a sztring formátuma a "Server=tcp:<your-database-name>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<your-user-name>;Password=<your-password>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;" formátumhoz hasonló.

   {
     "SearchServiceEndPoint": "<placeholder-search-full-url>",
     "SearchServiceAdminApiKey": "<placeholder-admin-key-for-search-service>",
     "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
   }
   

5. Cserélje le a felhasználói jelszót az SQL kapcsolati karakterlánc érvényes jelszavára. Amíg az adatbázis és a felhasználónevek át lesznek másolva, manuálisan kell megadnia a jelszót.

A csővezeték létrehozása

Az indexelőknek adatforrás-objektumra és indexre van szükségük. A megfelelő kód a következő két fájlban található meg:

• hotel.cs tartalmaz egy sémát, amely meghatározza az indexet
• Program.cs a szolgáltatás struktúráinak létrehozására és kezelésére szolgáló függvényeket tartalmaz

A hotel.cs fájlban

Az indexséma meghatározza a mezők gyűjteményét, beleértve az engedélyezett műveleteket meghatározó attribútumokat is, például azt, hogy egy mező kereshető, szűrhető vagy rendezhető-e, ahogyan az a következő meződefinícióban HotelNamelátható. A SearchableField definíció szerint teljes szöveges kereshető. Más attribútumok explicit módon vannak hozzárendelve.

. . . 
[SearchableField(IsFilterable = true, IsSortable = true)]
[JsonPropertyName("hotelName")]
public string HotelName { get; set; }
. . .

A sémák más elemeket is tartalmazhatnak, például pontozási profilokat a keresési pontszám növeléséhez és az egyéni elemzőket. Ebben az oktatóanyagban azonban a séma ritkán van definiálva, és csak a mintaadatkészletekben található mezőkből áll.

A Program.cs fájlban

A fő program magában foglalja a an indexelő ügyfél, index, adatforrás és indexelő létrehozásának logikáját. A kód ellenőrzi és törli az azonos nevű meglévő erőforrásokat, feltéve, hogy ezt a programot többször is futtathatja.

Az adatforrás-objektum olyan beállításokkal van konfigurálva, amelyek Azure SQL Database erőforrásokra vonatkoznak, beleértve a partiális vagy növekményes indexelést a beépített changeészlelési funkciók Azure SQL használatára. A Azure SQL forrás demóhotel-adatbázisában egy IsDeleted nevű "helyreállítható törlés" oszlop található. Ha ez az oszlop igaz értékre van állítva az adatbázisban, az indexelő eltávolítja a megfelelő dokumentumot a Azure AI Keresés indexből.

Console.WriteLine("Creating data source...");

var dataSource =
      new SearchIndexerDataSourceConnection(
         "hotels-sql-ds",
         SearchIndexerDataSourceType.AzureSql,
         configuration["AzureSqlConnectionString"],
         new SearchIndexerDataContainer("hotels"));

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

Az indexelő objektum platformfüggetlen, ahol a konfiguráció, az ütemezés és a hívás a forrástól függetlenül azonos. Ez a példa indexelő tartalmaz egy ütemezést és egy visszaállítási beállítást, amely törli az indexelő előzményeket. Egy metódust is meghív az indexelő azonnali létrehozásához és futtatásához. Indexelő létrehozásához vagy frissítéséhez használja a CreateOrUpdateIndexerAsync.

Console.WriteLine("Creating Azure SQL indexer...");

var schedule = new IndexingSchedule(TimeSpan.FromDays(1))
{
      StartTime = DateTimeOffset.Now
};

var parameters = new IndexingParameters()
{
      BatchSize = 100,
      MaxFailedItems = 0,
      MaxFailedItemsPerBatch = 0
};

// Indexer declarations require a data source and search index.
// Common optional properties include a schedule, parameters, and field mappings
// The field mappings below are redundant due to how the Hotel class is defined, but 
// we included them anyway to show the syntax 
var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
      Description = "Data indexer",
      Schedule = schedule,
      Parameters = parameters,
      FieldMappings =
      {
         new FieldMapping("_id") {TargetFieldName = "HotelId"},
         new FieldMapping("Amenities") {TargetFieldName = "Tags"}
      }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

Az indexelő futtatása általában ütemezett, de a fejlesztés során érdemes lehet azonnal futtatni az indexelőt a RunIndexerAsync használatával.

Console.WriteLine("Running Azure SQL indexer...");

try
{
      await indexerClient.RunIndexerAsync(indexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
      Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

A megoldás létrehozása

Válassza az F5 lehetőséget a megoldás létrehozásához és futtatásához. A program hibakeresési módban lesz végrehajtva. Az egyes műveletek állapota a konzolablakban látható.

A kód helyileg fut a Visual Studio-ban, és csatlakozik az Azure keresési szolgáltatásához, amely viszont csatlakozik az Azure SQL Database-hez, és lekéri az adathalmazt. Ezzel a sok művelettel több lehetséges meghibásodási pont is lehet. Ha hibaüzenetet kap, először ellenőrizze a következő feltételeket:

• A keresési szolgáltatás megadott kapcsolati adatai a teljes URL-cím. Ha csak a szolgáltatás nevét adta meg, a műveletek leállnak az index létrehozásakor, kapcsolódási hiba miatt.

• Az adatbázis kapcsolati adatai az appsettings.json fájlban. Az Azure portálról beszerzett ADO.NET kapcsolatláncnak kell lennie, amely úgy van módosítva, hogy tartalmazza az érvényes felhasználónevet és jelszót az adatbázishoz. A felhasználói fióknak megfelelő engedéllyel kell rendelkeznie az adatok lekérdezéséhez. A helyi ügyfél IP-címén engedélyeznie kell a bejövő hozzáférést a tűzfalon keresztül.

• Erőforráskorlátok. Ne feledje, hogy az ingyenes szint három indexből, indexelőből és adatforrásból álló korlátokkal rendelkezik. A maximális korláton lévő szolgáltatások nem hozhatnak létre új objektumokat.

Kereső

Az objektumlétrehozás ellenőrzéséhez használja a Azure portal, majd a Search Explorer használatával kérdezheti le az indexet.

1. Nyissa meg a keresési szolgáltatást az Azure Portalon.

2. A bal oldali panelen nyissa meg az egyes lapokat az objektumok létrehozásának ellenőrzéséhez. Az indexelőknek, az indexelőknek és az adatforrásoknakhotels-sql-idx, hotels-sql-idxr és hotels-sql-ds értékekkel kell rendelkezniük.

3. Az Indexek lapon válassza ki a hotels-sql-idx indexet. A Hotelek lapon a Kereséskezelő az első lap.

4. Üres lekérdezés kiadásához válassza a Keresés lehetőséget .

   A rendszer az indexben lévő három bejegyzést JSON-dokumentumként adja vissza. A keresési ablak a dokumentumokat JSON-formátumban adja vissza, így a teljes struktúra megtekinthető.

   

5. Váltson JSON-nézetre , hogy meg tudja adni a lekérdezési paramétereket.

   {
        "search": "river",
        "count": true
   }
   

   Ez a lekérdezés teljes szöveges keresést hív meg a kifejezésen river. Az eredmény tartalmazza az egyező dokumentumok számát. Az egyező dokumentumok számának visszaadása olyan tesztelési helyzetekben hasznos, ahol több ezer vagy több millió dokumentumot tartalmazó nagy index van. Ebben az esetben a lekérdezésnek csak egy dokumentum felel meg.

6. Adja meg azokat a paramétereket, amelyek a keresési eredményeket érdeklődési körökre korlátozzák.

   {
        "search": "river",
        "select": "hotelId, hotelName, baseRate, description",
        "count": true
   }
   

   A lekérdezési válasz csak a kiválasztott mezőket tartalmazza, így a kimenet tömörebb lesz.

Alaphelyzetbe állítás és ismételt futtatás

A fejlesztés korai kísérleti szakaszaiban a tervezési iteráció legpraktikusabb módszere az objektumok törlése az Azure AI Keresés-ből, és a kód újraépítésének engedélyezése. Az erőforrásnevek egyediek. Egy objektum törlése révén újból létrehozhatja azt ugyanazzal a névvel.

Az oktatóanyag mintakódja ellenőrzi a meglévő objektumokat, és törli őket, hogy újrafuttassa a kódot.

A Azure portal indexek, indexelők és adatforrások törlésére is használható.

Az erőforrások rendbetétele

Ha a saját előfizetésében dolgozik, egy projekt végén célszerű eltávolítani a fölöslegessé vált erőforrásokat. A továbbra is futó erőforrások költségekkel járhatnak. Az erőforrásokat törölheti egyesével, vagy az erőforráscsoport törlésével eltávolíthatja a benne lévő összes erőforrást is.

A bal oldali navigációs panel Minden erőforrás vagy Erőforráscsoport hivatkozásával megtalálhatja és kezelheti az erőforrásokat a Azure portal.

Következő lépések

Most, hogy megismerte az SQL Database-indexelés alapjait, tekintse meg közelebbről az indexelő konfigurációját: