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

Cikk
01/19/2024

Konfiguráljon egy indexelőt, hogy kereshető adatokat nyerjen ki az Azure SQL Database-ből, és küldje el azokat egy keresési indexbe az Azure AI Searchben.

Ez az oktatóanyag a C# és az Azure SDK for .NET használatával hajtja végre a következő feladatokat:

Azure SQL Database-hez csatlakozó adatforrás létrehozása
Indexelő létrehozása
Indexelő futtatása adatok indexbe való betöltéséhez
Index lekérdezése ellenőrzési lépésként

Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.

Előfeltételek

Azure SQL Database SQL Server-hitelesítéssel
Visual Studio
Azure AI Search. Meglévő keresési szolgáltatás létrehozása vagy keresése

Feljegyzés

Ehhez az oktatóanyaghoz ingyenes keresési szolgáltatást használhat. Az ingyenes szint három indexre, három indexelőre és három adatforrásra korlátozza. Az oktatóanyagban mindegyikből egyet hozhat majd létre. Mielőtt hozzákezdene, győződjön meg arról, hogy van helye a szolgáltatásban az új erőforrások elfogadásához.

Fájlok letöltése

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

1 – Szolgáltatások létrehozása

Ez az oktatóanyag az Azure AI Search szolgáltatást használja indexeléshez és lekérdezésekhez, az Azure SQL Database-t pedig 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.

Az Azure SQL Database használata

Ez az oktatóanyag hotels.sql fájlt biztosít a mintaletöltésben az adatbázis feltöltéséhez. Az Azure AI Search egybesimított sorkészleteket használ fel, 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ással, a Megnyitás lekérdezés lépéstől kezdve hozzáadhatja hozzá a hotels táblát.

Hozzon létre egy Azure SQL-adatbázist a gyorsútmutató utasításaival : Egyetlen adatbázis létrehozása.

Az adatbázis kiszolgálókonfigurációja fontos.
- Válassza ki azt az SQL Server-hitelesítési lehetőséget, amely a felhasználónév és a jelszó megadását kéri. Erre az indexelő által használt ADO.NET kapcsolati sztring van szüksége.
- Válasszon nyilvános kapcsolatot. Ez megkönnyíti ezt az oktatóanyagot. A nyilvános nem ajánlott éles környezetben, és azt javasoljuk, hogy az oktatóanyag végén törölje ezt az erőforrást .
Az Azure Portalon lépjen az új erőforrásra.
Adjon hozzá egy tűzfalszabályt az ügyféltől való hozzáférés engedélyezéséhez a következő rövid útmutató utasításaival : Kiszolgálószintű tűzfalszabály létrehozása az Azure Portalon. A parancssorból futtatva ipconfig lekérheti az IP-címét.
Töltse be a mintaadatokat a Lekérdezésszerkesztővel. A navigációs panelen válassza a Lekérdezésszerkesztő (előzetes verzió) lehetőséget, és adja meg a kiszolgáló rendszergazdájának felhasználónevét és jelszavát.

Ha a hozzáférés megtagadása 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 engedélyezi az ügyféltől való hozzáférést.
A Lekérdezésszerkesztőben válassza a Lekérdezés megnyitása lehetőséget, és keresse meg hotels.sql fájl helyét a helyi számítógépen.
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:
Válassza a Futtatás lehetőséget a lekérdezés végrehajtásához. Az Eredmények panelen egy sikeres lekérdezési üzenetnek kell megjelennie három sorra vonatkozóan.
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
```

Másolja ki az adatbázis ADO.NET kapcsolati sztring. A Gépház> Csatlakozás ion-sztringek területen másolja ki a ADO.NET kapcsolati sztring az alábbi példához hasonlóan.

Server=tcp:{your_dbname}.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID={your_username};Password={your_password};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;

A következő gyakorlatban szüksége lesz erre a kapcsolati sztring a környezet beállítására.

Azure AI Keresés

A következő összetevő az Azure AI Search, amelyet a portálon hozhat létre. Az ingyenes szinttel elvégezheti ezt az útmutatót.

Rendszergazdai API-kulcs és URL-cím lekérése az Azure AI Search szolgáltatáshoz

Az API-hívásokhoz a szolgáltatás URL-címe és egy hozzáférési kulcs szükséges. Mindkét szolgáltatással létrejön egy keresési szolgáltatás, ezért ha hozzáadta az Azure AI Search szolgáltatást az előfizetéséhez, kövesse az alábbi lépéseket a szükséges információk beszerzéséhez:

Jelentkezzen be az Azure Portalra, és a keresési szolgáltatás áttekintési lapján kérje le az URL-címet. A végpontok például a következőképpen nézhetnek ki: https://mydemo.search.windows.net.
A Gépház> Keysben 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 elsődleges vagy a másodlagos kulcsot használhatja objektumok hozzáadására, módosítására és törlésére vonatkozó kérelmekhez.

2 – A környezet beállítása

Indítsa el a Visual Studiót, és nyissa meg a DotNetHowToIndexers.sln.
A Megoldáskezelő nyissa meg a appsettings.json a kapcsolati adatok megadásához.
Ha SearchServiceEndPointa szolgáltatás áttekintési oldalának teljes URL-címe "https://my-demo-service.search.windows.net", akkor a megadni kívánt érték a teljes URL-cím.
A AzureSqlConnectionStringsztring formátuma a következőhöz hasonló: "Server=tcp:{your_dbname}.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID={your_username};Password={your_password};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
```
{
  "SearchServiceEndPoint": "<placeholder-search-full-url>",
  "SearchServiceAdminApiKey": "<placeholder-admin-key-for-search-service>",
  "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
}
```
Cserélje le a felhasználói jelszót az SQL kapcsolati sztring egy érvényes jelszóra. Amíg az adatbázis és a felhasználónevek át lesznek másolva, a jelszót manuálisan kell megadni.

3 – A folyamat létrehozása

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

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

A hotel.cs fájlban

Az indexséma határozza meg a mezők gyűjteményét, beleértve az attribútumokat, amelyek megadják az engedélyezett műveleteket, például azt, hogy az adott mező alkalmas-e teljes szöveges keresésre, szűrésre vagy rendezésre, ahogy a HotelName alábbi mezőmeghatározása esetében is látható. A SearchableField definíció szerint kereshető teljes szöveges formátumban. 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 tartalmazhatnak egyéb elemeket is, például keresési pontszámok növelésére használt pontozási profilokat, egyéni elemzőket és egyéb szerkezeteket. Jelenlegi céljainknak megfelelően azonban a sémát kevés elem határozza meg, így csak a minta adatkészletekben lévő mezők találhatók meg benne.

A Program.cs fájlban

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

Az adatforrás-objektum olyan beállításokkal van konfigurálva, amelyek az Azure SQL Database-erőforrásokra vonatkoznak, beleértve a részleges vagy növekményes indexelést az Azure SQL beépített változásészlelési funkcióinak használatához. Az Azure SQL-ben a forrás demóhotelek adatbázisában van egy "helyreállítható törlés" oszlop isDeleted néven. Ha ez az oszlop igaz értékre van állítva az adatbázisban, az indexelő eltávolítja a megfelelő dokumentumot az Azure AI Search-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őzmény tartalmaz egy ütemezést, egy visszaállítási beállítást, amely törli az indexelőzményeket, és meghív egy metódust az indexelőzmények azonnali létrehozásához és futtatásához. Indexelő létrehozásához vagy frissítéséhez használja a CreateOrUpdateIndexerAsync parancsot.

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ások általában ütemezettek, 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);
}

4 – A megoldás létrehozása

A megoldás létrehozásához és futtatásához nyomja le az F5 billentyűt. 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 Studióban, és csatlakozik a keresési szolgáltatáshoz az Azure-ban, 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:

Search szolgáltatás megadott kapcsolati adatok a teljes URL-cím. Ha csak a szolgáltatásnevet adta meg, a műveletek leállnak az index létrehozásakor, és a kapcsolódási hiba meghiúsul.
Az adatbázis kapcsolati adatai az appsettings.json fájlban. Ennek a portálról beszerzett ADO.NET kapcsolati sztringnek kell lennie, amelyet úgy módosítottunk, hogy tartalmazza az adatbázishoz tartozó felhasználónevet és jelszót. A felhasználói fióknak megfelelő engedéllyel kell rendelkeznie az adatok lekérdezéséhez. A helyi ügyfél IP-címét engedélyezni kell a tűzfalon keresztüli bejövő hozzáféréshez.
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.

5 – Keresés

Az Azure Portalon ellenőrizheti az objektumok létrehozását, majd a Kereséskezelővel lekérdezheti az indexet.

Jelentkezzen be az Azure Portalra, és a keresési szolgáltatás bal oldali navigációs paneljén nyissa meg az egyes lapokat az objektum létrehozásának ellenőrzéséhez. Az indexelők, indexelők és adatforrások "hotels-sql-idx", "hotels-sql-indexer" és "hotels-sql-ds" típusúak lesznek.
Az Indexek lapon válassza ki a hotels-sql-idx indexet. A Hotelek lapon a Kereséskezelő az első lap.
Ü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ő.
Ezután 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 indít a river kifejezésre, az eredmény pedig tartalmazza az egyező dokumentumok darabszámát. Az egyező dokumentumok darabszámának visszaadása hasznos lehet az olyan forgatókönyvek tesztelése esetében, amelyekben több ezer vagy több millió dokumentumot tartalmazó, nagy méretű indexszel rendelkezik. Ebben az esetben a lekérdezésnek csak egy dokumentum felel meg.
Végül 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 fázisaiban a tervezési iteráció legpraktikusabb módszere az objektumok törlése az Azure AI Searchbő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 portálon indexeket, indexelőket és adatforrásokat is törölhet.

Az erőforrások eltávolítása

Ha a saját előfizetésében dolgozik, a projekt végén célszerű eltávolítania a már nem szükséges 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 portálon a bal oldali navigációs panel Minden erőforrás vagy Erőforráscsoport hivatkozásával kereshet és kezelhet erőforrásokat.

Következő lépések

Most, hogy megismerte az SQL Database indexelésének alapjait, tekintsük át közelebbről az indexelő konfigurációját.

SQL Database-indexelő konfigurálása

Megosztás a következőn keresztül: