Tutorial: Indeks dari beberapa sumber data menggunakan .NET SDK
Azure AI Search dapat mengimpor, menganalisis, dan mengindeks data dari beberapa sumber data ke dalam satu indeks pencarian terkonsolidasi.
Tutorial C# ini menggunakan pustaka klien Azure.Search.Documents di Azure SDK untuk .NET untuk mengindeks data hotel sampel dari instans Azure Cosmos DB, dan menggabungkannya dengan detail kamar hotel yang diambil dari dokumen Azure Blob Storage. Hasilnya adalah indeks pencarian hotel gabungan yang berisi dokumen hotel, dengan kamar sebagai jenis data yang kompleks.
Dalam tutorial ini, Anda akan melakukan tugas-tugas berikut:
- Mengunggah data sampel dan membuat sumber data
- Mengidentifikasi kunci dokumen
- Menentukan dan membuat indeks
- Mengindeks data hotel dari Azure Cosmos DB
- Menggabungkan data kamar hotel dari penyimpanan blob
Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.
Gambaran Umum
Tutorial ini menggunakan Azure.Search.Documents untuk membuat dan menjalankan beberapa pengindeks. Dalam tutorial ini, Anda akan menyiapkan dua sumber data Azure sehingga Anda dapat mengonfigurasi pengindeks yang menarik dari keduanya untuk mengisi satu indeks pencarian. Dua kumpulan data harus memiliki nilai yang sama untuk mendukung penggabungan. Dalam sampel ini, bidang itu adalah ID. Selama ada bidang yang sama untuk mendukung pemetaan, pengindeks dapat menggabungkan data dari sumber daya yang berbeda: data terstruktur dari Azure SQL, data yang tidak terstruktur dari penyimpanan Blob, atau kombinasi sumber data yang didukung di Azure.
Versi selesai kode dalam tutorial ini dapat ditemukan dalam proyek berikut:
Prasyarat
- Azure Cosmos DB for NoSQL
- Azure Storage
- Visual Studio
- Paket NuGet Azure AI Search (versi 11.x)
- Pencarian Azure AI
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 layanan dari masing-masing layanan. Sebelum memulai, pastikan Anda memiliki ruang pada layanan Anda untuk menerima sumber daya baru.
1 - Membuat layanan
Tutorial ini menggunakan Azure AI Search untuk pengindeksan dan kueri, Azure Cosmos DB untuk satu himpunan data, dan Azure Blob Storage untuk himpunan data kedua.
Jika memungkinkan, buat seluruh layanan di wilayah yang sama dan grup sumber daya untuk kedekatan dan pengelolaan. Dalam praktiknya, layanan Anda dapat berada di wilayah mana pun.
Sampel ini menggunakan dua rangkaian kecil data yang menggambarkan tujuh hotel fiktif. Satu rangkaian menggambarkan hotel itu sendiri, dan akan dimuat ke dalam database Azure Cosmos DB. Rangkaian lainnya berisi detail kamar hotel, dan disediakan sebagai tujuh file JSON terpisah yang akan diunggah ke Azure Blob Storage.
Mulai dengan Azure Cosmos DB
Masuk ke portal Microsoft Azure, lalu navigasikan halaman Ikhtisar akun Azure Cosmos DB Anda.
Pilih Data Explorer lalu pilih Database Baru.
Masukkan nama hotel-rooms-db. Terima nilai default untuk properti yang tersisa.
Buat kontainer baru. Gunakan database yang sudah ada yang baru saja Anda buat. Masukkan hotel untuk nama kontainer, dan gunakan /HotelId untuk tombol Partisi.
Pilih Item di bawah hotel, lalu pilih Unggah Item pada bilah perintah. Navigasikan lalu pilih file cosmosdb/HotelsDataSubset_CosmosDb.json di folder proyek.
Gunakan tombol Refresh untuk menyegarkan tampilan item di koleksi hotel. Anda akan melihat tujuh dokumen database baru yang tercantum.
Salin string koneksi dari halaman Tombol ke Notepad. Anda akan memerlukan nilai ini untuk appsettings.json di langkah selanjutnya. Jika Anda tidak menggunakan nama database yang disarankan "hotel-rooms-db", salin nama database juga.
Azure Blob Storage
Masuk ke portal Azure, navigasikan ke akun penyimpanan Azure Anda, pilih Blob, lalu pilih + Kontainer.
Buat kontainer blob bernama hotel-rooms untuk menyimpan contoh file JSON kamar hotel. Anda bisa mengatur Tingkat Akses Publik ke salah satu nilainya yang valid.
Setelah kontainer dibuat, buka dan pilih Unggah di bilah perintah. Navigasi ke folder yang berisi file sampel. Pilih semuanya lalu pilih Unggah.
Salin nama akun penyimpanan dan string koneksi dari halaman Kunci Akses ke Notepad. Anda akan memerlukan kedua nilai untuk appsettings.json di langkah selanjutnya.
Pencarian Azure AI
Komponen ketiga adalah Azure AI Search, yang dapat Anda buat di portal atau menemukan layanan pencarian yang ada di sumber daya Azure Anda.
Menyalin kunci api admin dan URL untuk Pencarian Azure AI
Untuk mengautentikasi ke layanan pencarian, Anda memerlukan URL layanan dan kunci akses.
Masuk ke portal Azure, dan di halaman Gambaran Umum layanan pencarian Anda, dapatkan URL. Contoh titik akhir mungkin terlihat seperti
https://mydemo.search.windows.net.Di Pengaturan>Kunci, dapatkan kunci admin untuk mendapatkan hak penuh atas 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.
Memiliki kunci yang valid akan membangun kepercayaan, berdasarkan per permintaan, antara aplikasi yang mengirim permintaan dan layanan yang menanganinya.
2 - Menyiapkan lingkungan Anda
Mulai Visual Studio dan di menu Alat, pilih Pengelola Paket NuGet lalu Kelola Paket NuGet untuk Solusi....
Di tab Telusuri, temukan lalu instal Azure.Search.Documents (versi 11.0 atau yang lebih baru).
Cari Microsoft.Extensions.Configuration dan Microsoft.Extensions.Configuration.Json paket NuGet dan instal.
Buka file solusi /v11/AzureSearchMultipleDataSources.sln.
Di Penjelajah Solusi, edit file appsettings.json untuk menambahkan informasi koneksi.
{ "SearchServiceUri": "<YourSearchServiceURL>", "SearchServiceAdminApiKey": "<YourSearchServiceAdminApiKey>", "BlobStorageAccountName": "<YourBlobStorageAccountName>", "BlobStorageConnectionString": "<YourBlobStorageConnectionString>", "CosmosDBConnectionString": "<YourCosmosDBConnectionString>", "CosmosDBDatabaseName": "hotel-rooms-db" }
Dua entri pertama adalah URL dan kunci admin layanan pencarian. Gunakan titik akhir, misalnya: https://mydemo.search.windows.net.
Entri berikutnya menentukan nama akun dan informasi string koneksi untuk sumber data Azure Blob Storage dan Azure Cosmos DB.
3 - Petakan bidang kunci
Menggabungkan konten mengharuskan kedua aliran data menargetkan dokumen yang sama dalam indeks pencarian.
Di Pencarian Azure AI, bidang kunci secara unik mengidentifikasi setiap dokumen. Setiap indeks pencarian harus memiliki satu bidang kunci tipe Edm.String. Bidang kunci tersebut harus ada untuk setiap dokumen dalam sumber data yang ditambahkan ke indeks. (Bahkan, itu adalah satu-satunya bidang yang diperlukan.)
Saat mengindeks data dari beberapa sumber data, pastikan setiap baris atau dokumen masuk berisi kunci dokumen umum untuk menggabungkan data dari dua dokumen sumber yang berbeda secara fisik ke dalam dokumen pencarian baru dalam indeks gabungan.
Seringkali diperlukan beberapa perencanaan di muka untuk mengidentifikasi kunci dokumen yang bermakna untuk indeks Anda, dan memastikannya ada di kedua sumber data. Dalam demo ini, HotelId kunci untuk setiap hotel di Azure Cosmos DB juga ada di blob JSON kamar di penyimpanan Blob.
Pengindeks Pencarian Azure AI dapat menggunakan pemetaan bidang untuk mengganti nama dan bahkan memformat ulang bidang data selama proses pengindeksan, sehingga data sumber dapat diarahkan ke bidang indeks yang benar. Misalnya, di Azure Cosmos DB, pengidentifikasi hotel disebut HotelId. Tetapi dalam file blob JSON untuk kamar hotel, pengidentifikasi hotel diberi nama Id. Program menangani perbedaan ini dengan memetakan Id bidang dari blob ke HotelId bidang kunci di pengindeks.
Catatan
Dalam kebanyakan kasus, tombol dokumen yang dibuat secara otomatis, seperti yang dibuat secara default oleh beberapa pengindeks, tidak membuat kunci dokumen yang baik untuk indeks gabungan. Secara umum Anda ingin menggunakan nilai kunci unik yang bermakna yang sudah ada, atau dapat dengan mudah ditambahkan, ke sumber data Anda.
4 - Jelajahi kode
Setelah pengaturan data dan konfigurasi diberlakukan, program sampel di /v11/AzureSearchMultipleDataSources.sln harus siap untuk membangun dan berjalan.
Aplikasi konsol C#/.NET sederhana ini melakukan tugas-tugas berikut:
- Membuat indeks baru berdasarkan struktur data kelas Hotel C# (yang juga mereferensikan kelas Alamat dan Kamar).
- Membuat sumber data baru dan pengindeks yang memetakan data Microsoft Azure Cosmos DB untuk mengindeks bidang. Ini adalah kedua objek dalam Azure AI Search.
- Menjalankan pengindeks untuk memuat data Hotel dari Azure Cosmos DB.
- Membuat sumber data kedua dan pengindeks yang memetakan data blob JSON ke bidang indeks.
- Menjalankan pengindeks kedua untuk memuat data Kamar dari penyimpanan Blob.
Sebelum menjalankan program, luangkan waktu satu menit untuk mempelajari kode dan definisi indeks untuk sampel ini. Kode yang relevan ada dalam dua file:
- Hotel.cs berisi skema yang mendefinisikan indeks
- Program.cs berisi fungsi yang membuat indeks Pencarian Azure AI, sumber data, dan pengindeks, dan memuat hasil gabungan ke dalam indeks.
Buat indeks
Program sampel ini menggunakan CreateIndexAsync untuk menentukan dan membuat indeks Pencarian Azure AI. Program ini memanfaatkan kelas FieldBuilder untuk menghasilkan struktur indeks dari kelas model data C#.
Model data ditentukan oleh kelas Hotel, yang juga berisi referensi ke kelas Alamat dan Kamar. FieldBuilder menelusuri detail beberapa definisi kelas untuk menghasilkan struktur data yang kompleks untuk indeks. Tag metadata digunakan untuk menentukan atribut setiap bidang, seperti apakah tag dapat dicari atau dapat diurutkan.
Program ini akan menghapus indeks yang ada dengan nama yang sama sebelum membuat yang baru, jika Anda ingin menjalankan contoh ini lebih dari sekali.
Cuplikan berikut dari file Hotel.cs memperlihatkan satu bidang, diikuti dengan referensi ke kelas model data lain, Room[], yang pada gilirannya didefinisikan dalam file Room.cs (tidak ditampilkan).
. . .
[SimpleField(IsFilterable = true, IsKey = true)]
public string HotelId { get; set; }
[SearchableField(IsFilterable = true, IsSortable = true)]
public string HotelName { get; set; }
. . .
public Room[] Rooms { get; set; }
. . .
Dalam file Program.cs, SearchIndex ditentukan dengan nama dan koleksi bidang yang dihasilkan oleh metode FieldBuilder.Build, lalu dibuat sebagai berikut:
private static async Task CreateIndexAsync(string indexName, SearchIndexClient indexClient)
{
// Create a new search index structure that matches the properties of the Hotel class.
// The Address and Room classes are referenced from the Hotel class. The FieldBuilder
// will enumerate these to create a complex data structure for the index.
FieldBuilder builder = new FieldBuilder();
var definition = new SearchIndex(indexName, builder.Build(typeof(Hotel)));
await indexClient.CreateIndexAsync(definition);
}
Membuat sumber data dan pengindeks Azure Cosmos DB
Selanjutnya program utama mencakup logika untuk membuat sumber data Microsoft Azure Cosmos DB untuk data hotel.
Pertama, program akan menggabungkan nama database Azure Cosmos DB ke string koneksi. Kemudian program akan mendefinisikan objek SearchIndexerDataSourceConnection.
private static async Task CreateAndRunCosmosDbIndexerAsync(string indexName, SearchIndexerClient indexerClient)
{
// Append the database name to the connection string
string cosmosConnectString =
configuration["CosmosDBConnectionString"]
+ ";Database="
+ configuration["CosmosDBDatabaseName"];
SearchIndexerDataSourceConnection cosmosDbDataSource = new SearchIndexerDataSourceConnection(
name: configuration["CosmosDBDatabaseName"],
type: SearchIndexerDataSourceType.CosmosDb,
connectionString: cosmosConnectString,
container: new SearchIndexerDataContainer("hotels"));
// The Azure Cosmos DB data source does not need to be deleted if it already exists,
// but the connection string might need to be updated if it has changed.
await indexerClient.CreateOrUpdateDataSourceConnectionAsync(cosmosDbDataSource);
Setelah sumber data dibuat, program ini menyiapkan pengindeks Azure Cosmos DB bernama hotel-rooms-cosmos-indexer.
Program ini akan memperbarui pengindeks yang ada dengan nama yang sama, menimpa pengindeks yang ada dengan konten kode di atas. Ini juga termasuk mengatur ulang dan menjalankan tindakan, jika Anda ingin menjalankan contoh ini lebih dari sekali.
Contoh berikut menentukan jadwal untuk pengindeks, sehingga akan berjalan sekali per hari. Anda bisa menghapus properti jadwal dari panggilan ini jika Anda tidak ingin pengindeks berjalan kembali secara otomatis di masa mendatang.
SearchIndexer cosmosDbIndexer = new SearchIndexer(
name: "hotel-rooms-cosmos-indexer",
dataSourceName: cosmosDbDataSource.Name,
targetIndexName: indexName)
{
Schedule = new IndexingSchedule(TimeSpan.FromDays(1))
};
// Indexers keep metadata about how much they have already indexed.
// If we already ran the indexer, it "remembers" and does not run again.
// To avoid this, reset the indexer if it exists.
try
{
await indexerClient.GetIndexerAsync(cosmosDbIndexer.Name);
// Reset the indexer if it exists.
await indexerClient.ResetIndexerAsync(cosmosDbIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
// If the indexer does not exist, 404 will be thrown.
}
await indexerClient.CreateOrUpdateIndexerAsync(cosmosDbIndexer);
Console.WriteLine("Running Azure Cosmos DB indexer...\n");
try
{
// Run the indexer.
await indexerClient.RunIndexerAsync(cosmosDbIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}
Contoh ini mencakup blokir try-catch sederhana untuk melaporkan kesalahan yang mungkin terjadi selama eksekusi.
Setelah pengindeks Azure Cosmos DB berjalan, indeks pencarian akan berisi serangkaian lengkap dokumen hotel sampel. Namun bidang kamar untuk setiap hotel akan menjadi larik kosong, karena sumber data Azure Cosmos DB menghilangkan detail kamar. Selanjutnya, program ini akan menarik dari penyimpanan Blob untuk memuat dan menggabungkan data ruangan.
Membuat sumber data penyimpanan Blob dan pengindeks
Untuk mendapatkan detail ruangan, program ini terlebih dahulu menyiapkan sumber data penyimpanan Blob untuk mereferensikan sekumpulan file blob JSON individual.
private static async Task CreateAndRunBlobIndexerAsync(string indexName, SearchIndexerClient indexerClient)
{
SearchIndexerDataSourceConnection blobDataSource = new SearchIndexerDataSourceConnection(
name: configuration["BlobStorageAccountName"],
type: SearchIndexerDataSourceType.AzureBlob,
connectionString: configuration["BlobStorageConnectionString"],
container: new SearchIndexerDataContainer("hotel-rooms"));
// The blob data source does not need to be deleted if it already exists,
// but the connection string might need to be updated if it has changed.
await indexerClient.CreateOrUpdateDataSourceConnectionAsync(blobDataSource);
Setelah sumber data dibuat, program ini menyiapkan pengindeks blob bernama hotel-rooms-blob-indexer, seperti yang ditunjukkan di bawah ini.
Blob JSON berisi bidang kunci yang dinamai Id alih-alih HotelId. Kode menggunakan kelas FieldMapping untuk memberi tahu pengindeks untuk mengarahkan nilai bidang Id ke kunci dokumen HotelId dalam indeks.
Pengindeks penyimpanan blob dapat menggunakan IndexingParameters untuk menentukan mode penguraian. Anda harus mengatur mode penguraian yang berbeda tergantung pada apakah blob mewakili satu dokumen, atau beberapa dokumen dalam blob yang sama. Dalam contoh ini, setiap blob mewakili satu dokumen JSON, sehingga kode menggunakan json mode penguraian. Untuk informasi selengkapnya tentang parameter penguraian pengindeks untuk blob JSON, lihat Indeks blob JSON.
Contoh berikut menentukan jadwal untuk pengindeks, sehingga akan berjalan sekali per hari. Anda bisa menghapus properti jadwal dari panggilan ini jika Anda tidak ingin pengindeks berjalan kembali secara otomatis di masa mendatang.
IndexingParameters parameters = new IndexingParameters();
parameters.Configuration.Add("parsingMode", "json");
SearchIndexer blobIndexer = new SearchIndexer(
name: "hotel-rooms-blob-indexer",
dataSourceName: blobDataSource.Name,
targetIndexName: indexName)
{
Parameters = parameters,
Schedule = new IndexingSchedule(TimeSpan.FromDays(1))
};
// Map the Id field in the Room documents to the HotelId key field in the index
blobIndexer.FieldMappings.Add(new FieldMapping("Id") { TargetFieldName = "HotelId" });
// Reset the indexer if it already exists
try
{
await indexerClient.GetIndexerAsync(blobIndexer.Name);
await indexerClient.ResetIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 404) { }
await indexerClient.CreateOrUpdateIndexerAsync(blobIndexer);
try
{
// Run the indexer.
await searchService.Indexers.RunAsync(blobIndexer.Name);
}
catch (CloudException e) when (e.Response.StatusCode == (HttpStatusCode)429)
{
Console.WriteLine("Failed to run indexer: {0}", e.Response.Content);
}
Karena indeks telah diisi dengan data hotel dari database Azure Cosmos DB, pengindeks gumpalan memperbarui dokumen yang ada dalam indeks dan menambahkan detail kamar.
Catatan
Jika Anda memiliki bidang non-kunci yang sama di kedua sumber data Anda, dan data di dalam bidang tersebut tidak cocok, maka indeks akan berisi nilai dari pengindeks mana pun yang terakhir dijalankan. Dalam contoh kita, kedua sumber data berisi bidang HotelName. Jika karena alasan tertentu data di bidang ini berbeda, untuk dokumen dengan nilai kunci yang sama, maka data HotelName dari sumber data yang diindeks baru-baru ini akan menjadi nilai yang disimpan dalam indeks.
5 - Pencarian
Anda dapat menjelajahi indeks pencarian yang diisi setelah program berjalan secara terprogram atau menggunakan Search explorer di portal.
Di portal Microsoft Azure, buka halaman Ikhtisar layanan pencarian, dan temukan indeks hotel-rooms-sample di daftar Indeks.
Pilih indeks hotel-rooms-sample dalam daftar. Anda akan melihat antarmuka Search Explorer untuk indeks. Masukkan kueri untuk istilah seperti "Kemewahan". Anda akan melihat setidaknya satu dokumen dalam hasil, dan dokumen ini harus menampilkan daftar objek kamar di larik kamar.
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 sumber daya unik. Menghapus objek memungkinkan Anda membuatnya kembali menggunakan nama yang sama.
Kode sampel memeriksa objek yang ada dan menghapus atau memperbaruinya sehingga Anda dapat menjalankan ulang program.
Anda juga dapat menggunakan portal 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, menggunakan tautan Semua sumber daya atau Grup sumber daya di panel navigasi kiri.
Langkah berikutnya
Sekarang setelah Anda terbiasa dengan konsep menyerap data dari beberapa sumber, mari kita lihat lebih dekat konfigurasi pengindeks, dimulai dengan Azure Cosmos DB.