Samouczek: indeksowanie danych usługi Azure SQL przy użyciu zestawu SDK platformy .NET

Artykuł
09/23/2024

Skonfiguruj indeksator w celu wyodrębnienia danych z możliwością wyszukiwania z usługi Azure SQL Database, wysyłając je do indeksu wyszukiwania w usłudze Azure AI Search.

W tym samouczku do wykonywania następujących zadań są używane język C# i zestaw Azure SDK dla platformy .NET :

Tworzenie źródła danych łączącego się z usługą Azure SQL Database
Tworzenie indeksatora
Uruchamianie indeksatora w celu załadowania danych do indeksu
Wykonywanie zapytań względem indeksu jako kroku weryfikacji

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

Wymagania wstępne

Usługa Azure SQL Database korzystająca z uwierzytelniania programu SQL Server
Program Visual Studio
Azure AI Search. Tworzenie lub znajdowanie istniejącej usługi wyszukiwania

Uwaga

W tym samouczku możesz użyć bezpłatnej usługi wyszukiwania. Warstwa Bezpłatna ogranicza do trzech indeksów, trzech indeksatorów i trzech źródeł danych. W ramach tego samouczka tworzony jest jeden element każdego z tych typów. Przed rozpoczęciem upewnij się, że masz pokój w usłudze, aby zaakceptować nowe zasoby.

Pobieranie plików

Kod źródłowy tego samouczka znajduje się w folderze DotNetHowToIndexer w repozytorium GitHub Azure-Samples/search-dotnet-getting-started .

1 — Tworzenie usług

W tym samouczku użyto usługi Azure AI Search do indeksowania i zapytań oraz usługi Azure SQL Database jako zewnętrznego źródła danych. Jeśli to możliwe, utwórz obie usługi w tym samym regionie i grupie zasobów w celu zapewnienia zbliżenia i możliwości zarządzania. W praktyce usługa Azure SQL Database może znajdować się w dowolnym regionie.

Rozpoczynanie pracy z usługą Azure SQL Database

Ten samouczek zawiera plik hotels.sql w przykładowym pobieraniu w celu wypełnienia bazy danych. Usługa Azure AI Search zużywa spłaszczone zestawy wierszy, takie jak jedna wygenerowana z widoku lub zapytania. Plik SQL w przykładowym rozwiązaniu umożliwia utworzenie i wypełnienie pojedynczej tabeli.

Jeśli masz istniejący zasób usługi Azure SQL Database, możesz dodać do niej tabelę hotels, zaczynając od kroku Otwórz zapytanie .

Utwórz bazę danych Azure SQL Database, korzystając z instrukcji w przewodniku Szybki start: tworzenie pojedynczej bazy danych.

Konfiguracja serwera dla bazy danych jest ważna.
- Wybierz opcję uwierzytelniania programu SQL Server z monitem o podanie nazwy użytkownika i hasła. Jest to potrzebne dla ADO.NET parametry połączenia używanych przez indeksator.
- Wybierz połączenie publiczne. Ułatwia to ukończenie tego samouczka. Publiczne nie jest zalecane w środowisku produkcyjnym i zalecamy usunięcie tego zasobu na końcu samouczka.
W witrynie Azure Portal przejdź do nowego zasobu.
Dodaj regułę zapory, aby zezwolić na dostęp z klienta, korzystając z instrukcji w przewodniku Szybki start: tworzenie reguły zapory na poziomie serwera w witrynie Azure Portal. Możesz uruchomić ipconfig polecenie w wierszu polecenia, aby uzyskać adres IP.
Użyj edytora zapytań, aby załadować przykładowe dane. W okienku nawigacji wybierz pozycję Edytor zapytań (wersja zapoznawcza) i wprowadź nazwę użytkownika i hasło administratora serwera.

Jeśli wystąpi błąd odmowy dostępu, skopiuj adres IP klienta z komunikatu o błędzie, otwórz stronę zabezpieczeń sieci dla serwera i dodaj regułę ruchu przychodzącego, która zezwala na dostęp z klienta.
W edytorze zapytań wybierz pozycję Otwórz zapytanie i przejdź do lokalizacji pliku hotels.sql na komputerze lokalnym.
Wybierz plik i wybierz pozycję Otwórz. Skrypt powinien być podobny do tego na poniższym zrzucie ekranu:
Wybierz pozycję Uruchom, aby wykonać zapytanie. W okienku Wyniki powinien zostać wyświetlony komunikat o pomyślnym zakończeniu zapytania dla trzech wierszy.
Aby zwrócić zestaw wierszy z tej tabeli, w ramach kroku weryfikacyjnego możesz wykonać następujące zapytanie:
```
SELECT * FROM Hotels
```

Skopiuj ADO.NET parametry połączenia dla bazy danych. W obszarze Ustawienia>Parametry połączenia skopiuj ADO.NET parametry połączenia, podobnie jak w poniższym przykładzie.

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;

Ta parametry połączenia będzie potrzebna w następnym ćwiczeniu, konfigurując środowisko.

Wyszukiwanie AI platformy Azure

Następnym składnikiem jest usługa Azure AI Search, którą można utworzyć w portalu. Aby ukończyć ten przewodnik, możesz użyć warstwy Bezpłatna.

Uzyskiwanie klucza i adresu URL administratora dla usługi Azure AI Search

Wywołania interfejsu API wymagają adresu URL usługi i klucza dostępu. Usługa wyszukiwania jest tworzona przy użyciu obu tych elementów, więc jeśli usługa Azure AI Search została dodana do subskrypcji, wykonaj następujące kroki, aby uzyskać niezbędne informacje:

Zaloguj się do witryny Azure Portal i na stronie Przegląd usługi wyszukiwania uzyskaj adres URL. Przykładowy punkt końcowy może wyglądać podobnie jak https://mydemo.search.windows.net.
W obszarze Klucze ustawień>uzyskaj klucz administratora dla pełnych praw w usłudze. Istnieją dwa zamienne klucze administratora, które zapewniają ciągłość działania na wypadek konieczności przerzucania jednego. Możesz użyć klucza podstawowego lub pomocniczego na żądaniach dodawania, modyfikowania i usuwania obiektów.

2 — Konfigurowanie środowiska

Uruchom program Visual Studio i otwórz DotNetHowToIndexers.sln.
W Eksplorator rozwiązań otwórz appsettings.json, aby podać informacje o połączeniu.
W przypadku SearchServiceEndPointelementu , jeśli pełny adres URL na stronie przeglądu usługi to "https://my-demo-service.search.windows.net", wartość do podania to cały adres URL.
W przypadku AzureSqlConnectionStringparametru format ciągu jest podobny do następującego: "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;"
```
{
  "SearchServiceEndPoint": "<placeholder-search-full-url>",
  "SearchServiceAdminApiKey": "<placeholder-admin-key-for-search-service>",
  "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
}
```
Zastąp hasło użytkownika w parametry połączenia SQL prawidłowym hasłem. Chociaż baza danych i nazwy użytkowników zostaną skopiowane, hasło musi zostać wprowadzone ręcznie.

3 — Tworzenie potoku

Indeksatory wymagają obiektu źródła danych i indeksu. Odpowiedni kod znajduje się w dwóch plikach:

hotel.cs zawierający schemat definiujący indeks
Program.cs zawierające funkcje do tworzenia struktur w usłudze i zarządzania nimi

W pliku hotel.cs

Schemat indeksu definiuje kolekcję pól, w tym atrybuty określające dozwolone operacje, takie jak wyszukiwanie pełnotekstowe, filtrowanie lub sortowanie w polu, jak pokazano w poniższej definicji pola HotelName. Pole wyszukiwania jest wyszukiwaniem pełnotekstowym według definicji. Inne atrybuty są przypisywane jawnie.

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

Schemat może również obejmować inne elementy, w tym profile oceniania na potrzeby poprawiania wyniku wyszukiwania, niestandardowe analizatory i inne konstrukcje. Jednak na nasze potrzeby zdefiniowaliśmy bardzo prosty schemat, który zawiera tylko pola znalezione w przykładowych bazach danych.

W pliku Program.cs

Główny program obejmuje logikę tworzenia klienta indeksatora, indeksu, źródła danych i indeksatora. Kod sprawdza i usuwa istniejące zasoby o tej samej nazwie, przy założeniu, że ten program może być uruchamiany wiele razy.

Obiekt źródła danych jest konfigurowany przy użyciu ustawień specyficznych dla zasobów usługi Azure SQL Database, w tym indeksowania częściowego lub przyrostowego na potrzeby korzystania z wbudowanych funkcji wykrywania zmian usługi Azure SQL. Źródłowa baza danych hoteli demonstracyjnych w usłudze Azure SQL ma kolumnę "usuwanie nietrwałe" o nazwie IsDeleted. Gdy ta kolumna ma wartość true w bazie danych, indeksator usuwa odpowiedni dokument z indeksu usługi Azure AI Search.

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

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

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

Obiekt indeksatora jest niezależny od platformy, gdzie konfiguracja, planowanie i wywołanie są takie same niezależnie od źródła. Ten przykładowy indeksator zawiera harmonogram, opcję resetowania, która czyści historię indeksatora i wywołuje metodę do natychmiastowego utworzenia i uruchomienia indeksatora. Aby utworzyć lub zaktualizować indeksator, użyj polecenia 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);

Przebiegi indeksatora są zwykle zaplanowane, ale podczas opracowywania indeksator może być konieczne natychmiastowe uruchomienie indeksatora przy użyciu polecenia RunIndexerAsync.

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 — Tworzenie rozwiązania

Naciśnij F5, aby skompilować i uruchomić rozwiązanie. Program będzie działać w trybie debugowania. Stan każdej operacji będzie zgłaszany w oknie konsoli.

Kod działa lokalnie w programie Visual Studio, łącząc się z usługą wyszukiwania na platformie Azure, która z kolei łączy się z usługą Azure SQL Database i pobiera zestaw danych. W przypadku wielu operacji istnieje kilka potencjalnych punktów awarii. Jeśli wystąpi błąd, najpierw sprawdź następujące warunki:

usługa wyszukiwania podane informacje o połączeniu to pełny adres URL. Jeśli wprowadzono tylko nazwę usługi, operacje zatrzymają się podczas tworzenia indeksu z powodu błędu połączenia.
Informacje o połączeniu z bazą danych w pliku appsettings.json. Powinny to być parametry połączenia ADO.NET uzyskane z portalu i zmodyfikowane w celu uwzględnienia nazwy użytkownika i hasła, które obowiązują w przypadku Twojej bazy danych. Konto użytkownika musi mieć uprawnienia do pobierania danych. Adres IP klienta lokalnego musi mieć dozwolony dostęp przychodzący przez zaporę.
Limity zasobów. Pamiętaj, że warstwa Bezpłatna ma limity trzech indeksów, indeksatorów i źródeł danych. Usługa o maksymalnym limicie nie może tworzyć nowych obiektów.

5 — Wyszukiwanie

Użyj witryny Azure Portal, aby zweryfikować tworzenie obiektu, a następnie użyć Eksploratora wyszukiwania do wykonywania zapytań względem indeksu.

Zaloguj się do witryny Azure Portal, a w lewym okienku nawigacji usługi wyszukiwania otwórz każdą stronę, aby sprawdzić, czy obiekt został utworzony. Indeksy, indeksatory i źródła danych będą mieć odpowiednio "hotels-sql-idx", "hotels-sql-indexer" i "hotels-sql-ds".
Na karcie Indeksy wybierz indeks hotels-sql-idx. Na stronie hoteli eksplorator wyszukiwania jest pierwszą kartą.
Wybierz pozycję Wyszukaj , aby wydać puste zapytanie.

Trzy wpisy w indeksie zostaną zwrócone jako dokumenty JSON. Eksplorator wyszukiwania zwraca dokumenty w formacie JSON, tak, aby można było przeglądać całą strukturę.
Następnie przejdź do widoku JSON, aby można było wprowadzić parametry zapytania:
```
{
     "search": "river",
     "count": true
}
```
To zapytanie powoduje wywołanie wyszukiwania pełnotekstowego terminu river, a wynik obejmuje również liczbę pasujących dokumentów. Zwracanie liczby pasujących dokumentów jest przydatne w przypadku testowania scenariuszy, jeśli masz duży indeks z tysiącami lub milionami dokumentów. W takim przypadku tylko jeden dokument pasuje do zapytania.
Na koniec wprowadź parametry ograniczające wyniki wyszukiwania do interesujących pól:
```
{
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}
```
Odpowiedź na zapytanie jest redukowana do wybranych pól, co zapewnia bardziej zwięzły widok danych wyjściowych.

Resetowanie i ponowne uruchamianie

Na wczesnym etapie eksperymentalnym programowania najbardziej praktycznym podejściem do iteracji projektowej jest usunięcie obiektów z usługi Azure AI Search i umożliwienie ponownego kompilowania kodu. Nazwy zasobów są unikatowe. Usunięcie obiektu umożliwia jego ponowne utworzenie przy użyciu tej samej nazwy.

Przykładowy kod tego samouczka sprawdza istniejące obiekty i usuwa je, aby można było ponownie uruchomić kod.

Za pomocą portalu można również usuwać indeksy, indeksatory i źródła danych.

Czyszczenie zasobów

Gdy pracujesz we własnej subskrypcji, na końcu projektu warto usunąć zasoby, których już nie potrzebujesz. Uruchomione zasoby mogą generować koszty. Zasoby możesz usuwać pojedynczo lub jako grupę zasobów, usuwając cały zestaw zasobów.

Zasoby można znaleźć w portalu i zarządzać nimi, korzystając z linku Wszystkie zasoby lub Grupy zasobów w okienku nawigacji po lewej stronie.

Następne kroki

Teraz, gdy znasz już podstawy indeksowania usługi SQL Database, przyjrzyjmy się bliżej konfiguracji indeksatora.

Konfigurowanie indeksatora usługi SQL Database

Udostępnij za pośrednictwem