Tutorial: Indeks dari beberapa sumber data menggunakan .NET SDK

Pencarian Azure AI mendukung impor, analisis, dan pengindeksan 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. Anda kemudian menggabungkan data dengan detail kamar hotel yang digambar dari dokumen Azure Blob Storage. Hasilnya adalah indeks pencarian hotel gabungan yang berisi dokumen hotel, dengan kamar sebagai jenis data yang kompleks.

Di tutorial ini, Anda akan:

Mengunggah data sampel ke sumber data
Mengidentifikasi kunci dokumen
Menentukan dan membuat indeks
Mengindeks data hotel dari Azure Cosmos DB
Menggabungkan data kamar hotel dari Blob Storage

Gambaran Umum

Tutorial ini menggunakan Azure.Search.Documents untuk membuat dan menjalankan beberapa pengindeks. Anda mengunggah data sampel ke dua sumber data Azure dan mengonfigurasi sebuah komponen yang mengambil data dari kedua sumber untuk mengisi satu indeks pencarian. Dua kumpulan data harus memiliki nilai yang sama untuk mendukung penggabungan. Dalam tutorial ini, bidang tersebut 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 Blob Storage, atau kombinasi sumber data yang didukung di Azure.

Versi selesai kode dalam tutorial ini dapat ditemukan dalam proyek berikut:

multiple-data-sources/v11 (GitHub)

Prasyarat

Sebuah akun Azure dengan langganan aktif. Buat akun secara gratis.
Sebuah Akun Azure Cosmos DB untuk NoSQL.
Akun Azure Storage.
Layanan Pencarian Azure AI.
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 masing-masing. Sebelum memulai, pastikan Anda memiliki ruang pada layanan Anda untuk menerima sumber daya baru.

Menyiapkan layanan

Tutorial ini menggunakan Pencarian Azure AI untuk pengindeksan dan kueri, Azure Cosmos DB untuk himpunan data pertama, 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 set kecil data yang menjelaskan tujuh hotel fiktif. Satu set menjelaskan hotel itu sendiri dan akan dimuat ke dalam database Azure Cosmos DB. Set lainnya berisi detail kamar hotel dan disediakan sebagai tujuh file JSON terpisah untuk diunggah ke Azure Blob Storage.

Mulai dengan Azure Cosmos DB

Buka akun Azure Cosmos DB Anda di portal Microsoft Azure.
Dari panel kiri, pilih Data Explorer.
Pilih Kontainer Baru>Database Baru.
Masukkan hotel-rooms-db untuk namanya. Terima nilai default untuk pengaturan yang tersisa.
Buat kontainer yang menargetkan database yang sebelumnya Anda buat. Masukkan hotel untuk nama kontainer dan /HotelId untuk kunci partisi.
Pilih hotel>, lalu pilih Unggah Item pada bilah perintah.
Unggah file JSON dari cosmosdb folder di beberapa sumber data/v11.
Gunakan tombol refresh untuk me-refresh tampilan item di koleksi hotel. Anda akan melihat tujuh dokumen database baru yang tercantum.
Dari panel kiri, pilih Pengaturan>Tombol.
Buat catatan mengenai string koneksi. Anda memerlukan nilai ini untuk appsettings.json di langkah selanjutnya. Jika Anda tidak menggunakan nama database hotel-rooms-db yang disarankan, salin nama database juga.

Azure Blob Storage

Buka akun Azure Storage Anda di portal Microsoft Azure.
Dari panel kiri, pilih penyimpanan data>Kontainer.
Buat kontainer blob bernama hotel-rooms untuk menyimpan contoh file JSON kamar hotel. Anda dapat mengatur tingkat akses ke nilai yang valid.
Buka kontainer, lalu pilih Unggah pada bilah perintah.
Unggah tujuh file JSON dari blob folder di beberapa sumber data/v11.
Dari panel kiri, pilih Keamanan + kunci Akses jaringan>.
Catat nama akun dan string koneksi. Anda memerlukan kedua nilai untuk appsettings.json di langkah selanjutnya.

Pencarian Azure AI

Komponen ketiga adalah Pencarian Azure AI, yang dapat Anda buat di portal Azure atau menemukan layanan pencarian yang ada di sumber daya Azure Anda.

Menyalin kunci admin dan URL untuk Pencarian Azure AI

Untuk mengautentikasi ke layanan pencarian, Anda memerlukan URL layanan dan kunci akses. Memiliki kunci yang valid menetapkan kepercayaan berdasarkan per permintaan antara aplikasi yang mengirim permintaan dan layanan yang menanganinya.

Buka layanan pencarian Anda di portal Microsoft Azure.
Dari panel kiri, pilih Gambaran Umum.
Catat URL, yang akan terlihat seperti https://my-service.search.windows.net.
Dari panel kiri, pilih Pengaturan>Tombol.
Catat kunci admin untuk hak penuh pada layanan. Ada dua kunci admin yang dapat dipertukarkan. Kunci ini disediakan untuk kelangsungan bisnis jika Anda perlu menggantikan salah satunya. Anda dapat menggunakan salah satu kunci pada permintaan untuk menambahkan, memodifikasi, dan menghapus objek.

Atur lingkungan Anda

Buka file AzureSearchMultipleDataSources.sln dari beberapa sumber data/v11 di Visual Studio.
Di Penjelajah Solusi, klik kanan proyek dan pilih Kelola Paket NuGet untuk Solusi....
Pada tab Telusuri , temukan dan instal paket berikut ini:
- Azure.Search.Documents (versi 11.0 atau yang lebih baru)
- Microsoft.Extensions.Configuration
- Microsoft.Extensions.Configuration.Json

Di Penjelajah Solusi, edit appsettings.json file dengan informasi koneksi yang Anda kumpulkan di langkah-langkah sebelumnya.

{
  "SearchServiceUri": "<YourSearchServiceURL>",
  "SearchServiceAdminApiKey": "<YourSearchServiceAdminApiKey>",
  "BlobStorageAccountName": "<YourBlobStorageAccountName>",
  "BlobStorageConnectionString": "<YourBlobStorageConnectionString>",
  "CosmosDBConnectionString": "<YourCosmosDBConnectionString>",
  "CosmosDBDatabaseName": "hotel-rooms-db"
}

Memetakan 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. Ini memungkinkan Anda menggabungkan data dari dua dokumen sumber yang berbeda secara fisik ke dalam dokumen pencarian baru dalam indeks gabungan.

Ini sering memerlukan beberapa perencanaan di muka untuk mengidentifikasi kunci dokumen yang bermakna untuk indeks Anda dan untuk 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 Blob Storage.

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, kunci dokumen yang dibuat secara otomatis, seperti yang dibuat secara default oleh beberapa pengindeks, tidak membuat kunci dokumen yang baik untuk indeks gabungan. Secara umum, gunakan nilai kunci unik yang bermakna yang sudah ada di sumber data Anda atau dapat dengan mudah ditambahkan.

Jelajahi kode

Ketika data dan pengaturan konfigurasi sudah diterapkan, program sampel di AzureSearchMultipleDataSources.sln harus siap untuk dibangun dan dijalankan.

Aplikasi konsol C#/.NET sederhana ini melakukan tugas-tugas berikut:

Membuat indeks baru berdasarkan struktur data kelas C# Hotel, 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 Pencarian Azure AI.
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 hotel dari Blob Storage.

Sebelum Anda menjalankan program, luangkan waktu satu menit untuk mempelajari kode, definisi indeks, dan definisi pengindeks. Kode yang relevan ada dalam dua file:

Hotel.cs berisi skema yang menentukan 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 menghapus indeks yang ada dengan nama yang sama sebelum membuat yang baru, jika Anda ingin menjalankan contoh ini lebih dari sekali.

Cuplikan berikut dari Hotel.cs file memperlihatkan satu bidang, diikuti dengan referensi ke kelas model data lain, Room[], yang pada gilirannya didefinisikan dalam Room.cs file (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; }
. . .

Program.cs Dalam file tersebut, SearchIndex didefinisikan dengan nama dan kumpulan 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

Program utama mencakup logika untuk membuat sumber data Azure Cosmos DB untuk data hotel.

Pertama, ini menggabungkan nama database Azure Cosmos DB ke string koneksi. Kemudian 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 menyiapkan pengindeks Azure Cosmos DB bernama hotel-rooms-cosmos-indexer.

Program memperbarui pengindeks yang ada dengan nama yang sama, menggantikan pengindeks sebelumnya dengan isi kode yang sebelumnya digunakan. Ini juga mencakup aksi mengatur ulang dan menjalankan, jika Anda ingin menjalankan contoh ini lebih dari sekali.

Contoh berikut menentukan jadwal untuk pengindeks, sehingga 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 blok try-catch sederhana untuk melaporkan kesalahan yang mungkin terjadi selama proses eksekusi.

Setelah pengindeks Azure Cosmos DB berjalan, indeks pencarian berisi sekumpulan lengkap sampel dokumen hotel. Namun, kolom kamar untuk setiap hotel adalah array kosong, sebab sumber data Azure Cosmos DB tidak menyertakan detail kamar. Selanjutnya, program mengambil dari Blob Storage untuk memuat dan menggabungkan data kamar.

Membuat sumber data dan pengindeks Blob Storage

Untuk mendapatkan detail ruangan, program pertama-tama menyiapkan sumber data Blob Storage 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 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 Blob Storage 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 ini menentukan jadwal untuk pengindeks, sehingga 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 sudah diisi dengan data hotel dari database Azure Cosmos DB, pengindeks blob 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 bidang tersebut tidak cocok, maka indeks akan berisi nilai dari pengindeks yang paling baru dijalankan. Dalam contoh kami, kedua sumber data memiliki bidang HotelName. Jika karena alasan tertentu data di bidang ini berbeda, untuk dokumen dengan nilai kunci yang sama, HotelName data dari sumber data yang terakhir diindeks adalah nilai yang disimpan dalam indeks.

Cari

Setelah menjalankan program, Anda dapat menjelajahi indeks pencarian yang diisi menggunakan Penjelajah pencarian di portal Microsoft Azure.

Buka layanan pencarian Anda di portal Microsoft Azure.
Dari panel kiri, pilihIndeks> pencarian.
Pilih hotel-rooms-sample dari daftar indeks.
Pada tab Penjelajah pencarian , masukkan kueri untuk istilah seperti Luxury.

Anda akan melihat setidaknya satu dokumen dalam hasil. Dokumen ini harus berisi daftar objek-objek ruang dalam array-nya Rooms.

Atur ulang dan jalankan ulang

Pada tahap pengembangan eksperimental awal, pendekatan paling praktis untuk iterasi desain adalah menghapus objek dari Pencarian Azure AI dan memungkinkan kode Anda untuk membangunnya kembali. Nama-nama sumber daya bersifat 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 Azure untuk menghapus indeks, pengindeks, dan sumber data.

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, di akhir proyek, ada baiknya untuk menghapus 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 Microsoft Azure menggunakan tautan Semua sumber daya atau Grup sumber daya di panel kiri.

Langkah selanjutnya

Sekarang setelah Anda terbiasa dengan menyerap data dari beberapa sumber, lihat lebih dekat konfigurasi pengindeks, dimulai dengan Azure Cosmos DB:

Mengonfigurasi Azure Cosmos DB untuk pengindeks NoSQL

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-27

Tutorial: Indeks dari beberapa sumber data menggunakan .NET SDK

Gambaran Umum

Prasyarat

Menyiapkan layanan

Mulai dengan Azure Cosmos DB

Azure Blob Storage

Pencarian Azure AI

Menyalin kunci admin dan URL untuk Pencarian Azure AI

Atur lingkungan Anda

Memetakan bidang kunci

Jelajahi kode

Buat indeks

Membuat sumber data dan pengindeks Azure Cosmos DB

Membuat sumber data dan pengindeks Blob Storage

Cari

Atur ulang dan jalankan ulang

Membersihkan sumber daya

Langkah selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: