Tutorial: Mengindeks data Azure SQL menggunakan SDK .NET

2025-04-21

Pelajari cara mengonfigurasi pengindeks untuk mengekstrak data yang dapat dicari dari Azure SQL Database dan mengirimkannya ke indeks pencarian di Azure AI Search.

Dalam tutorial ini, Anda menggunakan C# dan Azure SDK untuk .NET untuk:

Membuat sumber data yang terhubung ke Azure SQL Database
Membuat pengindeks
Menjalankan pengindeks untuk memuat data ke dalam indeks
Membuat kueri indeks sebagai langkah verifikasi

Prasyarat

Sebuah akun Azure dengan langganan aktif. Buat akun secara gratis.
Azure SQL Database menggunakan autentikasi SQL Server.
Azure AI Search Buat layanan atau temukan layanan yang sudah ada di langganan Anda saat ini.
Visual Studio.

Catatan

Anda dapat menggunakan layanan pencarian gratis untuk tutorial ini. Tingkat Gratis membatasi Anda ke tiga indeks, tiga pengindeks, dan tiga sumber data. Tutorial ini membuat satu dari setiap jenis. Sebelum memulai, pastikan Anda memiliki ruang pada layanan Anda untuk menerima sumber daya baru.

Mengunduh file

Kode sumber untuk tutorial ini ada di folder DotNetHowToIndexer di repositori GitHub Azure-Samples/search-dotnet-getting-started.

Membuat layanan

Tutorial ini menggunakan Azure AI Search untuk pengindeksan dan kueri dan Azure SQL Database sebagai sumber data eksternal. Jika memungkinkan, buat kedua layanan di wilayah dan grup sumber daya yang sama untuk kedekatan dan pengelolaan. Dalam praktiknya, Azure SQL Database dapat berada di wilayah mana pun.

Mulai dengan Azure SQL Database

Tutorial ini menyediakan file hotels.sql dalam unduhan sampel untuk mengisi database. Azure AI Search menggunakan set data baris yang diratakan, seperti yang dihasilkan dari tampilan atau kueri. File SQL dalam solusi sampel membuat dan mengisi satu tabel.

Jika Anda memiliki sumber daya Azure SQL Database yang sudah ada, Anda bisa menambahkan tabel hotel ke dalamnya mulai dari langkah Buka kueri .

Membuat Azure SQL database. Konfigurasi server untuk database penting:
- Pilih opsi autentikasi SQL Server yang meminta Anda menentukan nama pengguna dan kata sandi. Anda memerlukan ini untuk ADO.NET string koneksi yang digunakan oleh pengindeks.
- Pilih koneksi publik, yang membuat tutorial ini lebih mudah diselesaikan. Publik tidak direkomendasikan untuk produksi, dan sebaiknya hapus sumber daya ini di akhir tutorial.
Di portal Azure, buka sumber daya baru.
Tambahkan aturan firewall yang memungkinkan akses dari klien Anda. Anda dapat menjalankan ipconfig dari prompt perintah untuk mendapatkan alamat IP Anda.
Gunakan editor Kueri untuk memuat data sampel. Pada panel navigasi, pilih Editor kueri (pratinjau) dan masukkan nama pengguna dan kata sandi admin server.

Jika Anda mendapatkan kesalahan akses ditolak, salin alamat IP klien dari pesan kesalahan, buka halaman keamanan jaringan untuk server, dan tambahkan aturan masuk yang memungkinkan akses dari klien Anda.
Di Editor kueri, pilih Buka kueri dan navigasikan ke lokasi file hotels.sql di komputer lokal Anda.
Pilih file dan pilih Buka. Skrip akan terlihat mirip dengan tangkapan layar berikut:
Pilih Jalankan untuk menjalankan kueri. Di panel Hasil , Anda akan melihat pesan kueri berhasil untuk tiga baris.
Untuk mengembalikan set baris dari tabel ini, Anda dapat menjalankan kueri berikut sebagai langkah verifikasi:
```
SELECT * FROM Hotels
```

Salin string koneksi ADO.NET untuk database. Di bawah Pengaturan>String Koneksi, salin string koneksi ADO.NET, yang harus mirip dengan contoh berikut:

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;

Anda akan memerlukan string koneksi ini untuk menyiapkan lingkungan Anda di langkah berikutnya.

Pencarian Azure AI

Komponen berikutnya adalah Azure AI Search, yang dapat Anda buat di portal Azure. Anda dapat menggunakan tingkat Gratis untuk menyelesaikan tutorial ini.

Mendapatkan kunci admin dan URL untuk Pencarian Azure AI

Panggilan API memerlukan URL layanan dan kunci akses. Layanan pencarian dibuat dengan keduanya, jadi jika Anda menambahkan Azure AI Search ke langganan Anda, ikuti langkah-langkah berikut untuk mendapatkan informasi yang diperlukan:

Masuk ke portal Azure. Pada halaman Gambaran Umum layanan Anda, salin URL titik akhir. Contoh titik akhir mungkin terlihat sepertihttps://mydemo.search.windows.net.
Pada Pengaturan>Kunci, dapatkan kunci admin untuk akses penuh ke layanan. Ada dua kunci admin yang dapat dipertukarkan, kunci disediakan untuk kelangsungan bisnis jika Anda perlu menimpa salah satunya. Anda dapat menggunakan kunci utama atau sekunder pada permintaan untuk menambahkan, memodifikasi, dan menghapus objek.

Atur lingkungan Anda

Mulai Visual Studio dan buka DotNetHowToIndexers.sln.
Di Penjelajah Solusi, buka appsettings.json untuk memberikan informasi koneksi.
Untuk SearchServiceEndPoint, jika URL lengkap di halaman Gambaran Umum layanan Anda adalah https://my-demo-service.search.windows.net, berikan seluruh URL.
Untuk AzureSqlConnectionString, format string mirip "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;"dengan .
```
{
  "SearchServiceEndPoint": "<placeholder-search-full-url>",
  "SearchServiceAdminApiKey": "<placeholder-admin-key-for-search-service>",
  "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
}
```
Ganti kata sandi pengguna dalam string koneksi SQL dengan kata sandi yang valid. Meskipun database dan nama pengguna akan disalin, Anda harus memasukkan kata sandi secara manual.

Membuat alur kerja

Pengindeks memerlukan objek sumber data dan indeks. Kode yang relevan ada dalam dua file:

hotel.cs berisi skema yang menentukan indeks
Program.cs berisi fungsi untuk membuat dan mengelola struktur dalam layanan Anda

Di hotel.cs

Skema indeks menentukan kumpulan bidang, termasuk atribut yang menentukan operasi yang diizinkan, seperti apakah bidang dapat dicari teks lengkap, dapat difilter, atau dapat diurutkan, seperti yang ditunjukkan dalam definisi bidang berikut untuk HotelName. SearchableField, menurut definisi, teks lengkap dapat dicari. Atribut lain secara eksplisit ditetapkan.

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

Skema juga dapat menyertakan elemen lain, seperti profil penilaian untuk meningkatkan skor pencarian dan penganalisis kustom. Namun, untuk tutorial ini, skema jarang ditentukan, hanya terdiri dari bidang yang ditemukan dalam himpunan data sampel.

Dalam Program.cs

Program utama mencakup logika untuk membuat klien pengindeks, indeks, sumber data, dan pengindeks. Kode memeriksa dan menghapus sumber daya yang ada dengan nama yang sama, dengan asumsi Anda mungkin menjalankan program ini beberapa kali.

Objek sumber data dikonfigurasi dengan pengaturan yang khusus untuk sumber daya Azure SQL Database, termasuk pengindeksan parsial atau inkremental untuk menggunakan fitur deteksi perubahan bawaan Azure SQL. Database hotel demo sumber di Azure SQL memiliki kolom "soft delete" bernama IsDeleted. Ketika kolom ini diatur ke true dalam database, pengindeks menghapus dokumen terkait dari indeks Pencarian Azure AI.

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

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

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

Objek pengindeks adalah agnostik platform, di mana konfigurasi, penjadwalan, dan pemanggilan sama terlepas dari sumbernya. Contoh pengindeks ini mencakup jadwal dan opsi reset yang menghapus riwayat pengindeks. Ini juga memanggil metode untuk segera membuat dan menjalankan pengindeks. Untuk membuat atau memperbarui pengindeks, gunakan 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);

Eksekusi pengindeks biasanya dijadwalkan, tetapi selama pengembangan, Anda mungkin ingin segera menjalankan pengindeks menggunakan 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);
}

Membuat solusi

Pilih F5 untuk membangun dan menjalankan solusi. Program ini dijalankan dalam mode debug. Jendela konsol melaporkan status setiap operasi.

Kode Anda berjalan secara lokal di Visual Studio, menghubungkan ke layanan pencarian Anda di Azure, yang pada gilirannya akan terhubung ke Azure SQL Database dan mengambil himpunan data. Dengan banyaknya operasi ini, ada beberapa kemungkinan titik kegagalan. Jika Anda mendapatkan kesalahan, periksa kondisi berikut terlebih dahulu:

Informasi koneksi layanan pencarian yang Anda berikan adalah URL lengkap. Jika Anda hanya memasukkan nama layanan, operasi berhenti pada pembuatan indeks, dengan kegagalan untuk menyambungkan kesalahan.
Informasi koneksi database ada di appsettings.json. Ini harus menjadi ADO.NET string koneksi yang diperoleh dari portal Azure, dimodifikasi untuk menyertakan nama pengguna dan kata sandi yang valid untuk database Anda. Akun pengguna harus memiliki izin untuk mengambil data. Alamat IP klien lokal Anda harus diizinkan masuk melalui firewall.
Batas sumber daya. Ingat bahwa tingkat Gratis memiliki batas tiga indeks, pengindeks, dan sumber data. Layanan pada batas maksimum tidak dapat membuat objek baru.

Cari

Gunakan portal Microsoft Azure untuk memverifikasi pembuatan objek, lalu gunakan Penjelajah pencarian untuk mengkueri indeks.

Masuk ke portal Microsoft Azure dan buka layanan pencarian Anda. Dari panel kiri, buka setiap halaman untuk memverifikasi objek dibuat. Indeks, Pengindeks, dan Sumber Data harus memiliki hotels-sql-idx, hotels-sql-indexer, dan hotels-sql-ds.
Pada tab Indeks , pilih indeks hotels-sql-idx . Pada halaman hotel, Jelajahi pencarian adalah tab pertama.
Pilih Cari untuk mengeluarkan kueri kosong.

Tiga entri dalam indeks Anda dikembalikan sebagai dokumen JSON. Penjelajah pencarian mengembalikan dokumen di JSON sehingga Anda bisa menampilkan seluruh struktur.
Beralih ke tampilan JSON sehingga Anda bisa memasukkan parameter kueri.
```
{
     "search": "river",
     "count": true
}
```
Kueri ini memanggil pencarian teks lengkap pada istilah river. Hasilnya mencakup hitungan dokumen yang cocok. Mengembalikan jumlah dokumen yang cocok sangat membantu dalam skenario pengujian di mana Anda memiliki indeks besar dengan ribuan atau jutaan dokumen. Dalam hal ini, hanya satu dokumen yang cocok dengan kueri.
Masukkan parameter yang membatasi hasil pencarian ke bidang yang diminati.
```
{
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}
```
Respons kueri dikurangi menjadi bidang yang dipilih, sehingga menghasilkan output yang lebih ringkas.

Atur ulang dan jalankan ulang

Pada tahap pengembangan eksperimental awal, pendekatan paling praktis untuk iterasi desain adalah menghapus objek dari Azure AI Search dan memungkinkan kode Anda untuk membangunnya kembali. Nama setiap sumber daya adalah unik. Menghapus objek memungkinkan Anda membuatnya kembali menggunakan nama yang sama.

Kode sampel untuk tutorial ini memeriksa objek yang ada dan menghapusnya agar Anda dapat menjalankan kembali kode Anda.

Anda juga dapat menggunakan portal Azure untuk menghapus indeks, pengindeks, dan sumber data.

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, di akhir proyek, sebaiknya hapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat menghabiskan uang Anda. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus seluruh rangkaian sumber daya.

Anda dapat menemukan dan mengelola sumber daya di portal Azure, menggunakan tautan Semua sumber daya atau Grup sumber daya di panel navigasi kiri.

Langkah berikutnya

Sekarang setelah Anda terbiasa dengan dasar-dasar pengindeksan SQL Database, lihat lebih dekat konfigurasi pengindeks:

Mengonfigurasi pengindeks basis data SQL