Öğretici: .NET SDK'sını kullanarak birden çok veri kaynağından dizin oluşturma

Azure Yapay Zeka Arama, birden çok veri kaynağındaki verilerin tek bir birleştirilmiş arama dizinine aktarılmasını, çözümlenmesini ve dizinlenmesini destekler.

Bu C# öğreticisi, bir Azure Cosmos DB örneğinden örnek otel verilerini dizine almak için .NET için Azure SDK'daki Azure.Search.Documents istemci kitaplığını kullanır. Ardından verileri Azure Blob Depolama belgelerinden alınan otel odası ayrıntılarıyla birleştirin. Sonuç, odaların karmaşık veri türleri olarak yer aldığı otel belgelerini içeren birleşik bir otel arama dizinidir.

Bu öğreticide şunları yapacaksınız:

Örnek verileri veri kaynaklarına yükleme
Belge anahtarını tanımlama
Dizini tanımlama ve oluşturma
Azure Cosmos DB'den otel verilerini dizine alın
Blob Depolama'dan otel odası verilerini birleştirme

Genel bakış

Bu öğreticide, birden çok dizin oluşturucu oluşturmak ve çalıştırmak için Azure.Search.Documents kullanılır. Örnek verileri iki Azure veri kaynağına yükler ve tek bir arama dizinini doldurmak için her iki kaynaktan da çeken bir dizin oluşturucu yapılandırabilirsiniz. Birleştirmeyi desteklemek için iki veri kümesinin ortak bir değeri olmalıdır. Bu öğreticide bu alan bir kimliktir. Eşlemeyi destekleyen ortak bir alan olduğu sürece, dizin oluşturucu farklı kaynaklardan verileri birleştirebilir: Azure SQL'den yapılandırılmış veriler, Blob Depolama'dan yapılandırılmamış veriler veya Azure'da desteklenen veri kaynaklarının herhangi bir bileşimi.

Bu öğreticideki kodun tamamlanmış bir sürümü aşağıdaki projede bulunabilir:

multiple-data-sources/v11 (GitHub)

Önkoşullar

Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
NoSQL için Azure Cosmos DB hesabı.
Bir Azure Depolama hesabı.
Azure Yapay Zeka Arama hizmeti.
Visual Studio.

Not

Bu öğretici için ücretsiz bir arama hizmeti kullanabilirsiniz. Ücretsiz katman sizi üç dizin, üç dizin oluşturucu ve üç veri kaynağıyla sınırlar. Bu öğretici her birinden bir tane oluşturur. Başlamadan önce, hizmetinizde yeni kaynakları kabul etmek için yer olduğundan emin olun.

Hizmetleri hazırlama

Bu öğreticide dizin oluşturma ve sorgular için Azure Yapay Zeka Arama, ilk veri kümesi için Azure Cosmos DB ve ikinci veri kümesi için Azure Blob Depolama kullanılır.

Mümkünse, yakınlık ve yönetilebilirlik için tüm hizmetleri aynı bölgede ve kaynak grubunda oluşturun. Pratikte hizmetleriniz herhangi bir bölgede olabilir.

Bu örnekte yedi hayali oteli açıklayan iki küçük veri kümesi kullanılmıştır. Bir küme, otelleri kendileri açıklar ve bir Azure Cosmos DB veritabanına yüklenir. Diğer küme otel odası ayrıntılarını içerir ve Azure Blob Depolama'ya yüklenecek yedi ayrı JSON dosyası olarak sağlanır.

Azure Cosmos DB ile çalışmaya başlama

Azure portalında Azure Cosmos DB hesabınıza gidin.
Sol bölmeden Veri Gezgini'ni seçin.
Yeni Kapsayıcı>Yeni Veritabanı'ni seçin.
Ad olarak hotel-rooms-db girin. Kalan ayarlar için varsayılan değerleri kabul edin.
Daha önce oluşturduğunuz veritabanını hedefleyen bir kapsayıcı oluşturun. Kapsayıcı adı için oteller ve bölüm anahtarı için /HotelId girin.
Oteller>Öğeler'i ve ardından komut çubuğunda Öğeyi Karşıya Yükle'yi seçin.
JSON dosyasını cosmosdb klasöründeki multiple-data-sources/v11 karşıya yükleyin.
Otel koleksiyonundaki öğelerin görünümünü yenilemek için yenile düğmesini kullanın. Yedi yeni veritabanı belgesinin listelendiğini görmeniz gerekir.
Sol bölmeden Ayarlar>Anahtarlar'ı seçin.
Bağlantı dizesini not edin. Sonraki bir adımda appsettings.json için bu değere ihtiyacınız vardır. Önerilen hotel-rooms-db veritabanı adını kullanmadıysanız veritabanı adını da kopyalayın.

Azure Blob Depolama

Azure portalında Azure Depolama hesabınıza gidin.
Sol bölmeden Veri depolama>Kapsayıcıları'nı seçin.
Örnek otel odası JSON dosyalarını depolamak için hotel-rooms adlı bir blob kapsayıcısı oluşturun. Erişim düzeyini geçerli herhangi bir değere ayarlayabilirsiniz.
Kapsayıcıyı açın ve ardından komut çubuğunda Karşıya Yükle'yi seçin.
blob klasöründen yedi JSON dosyasını karşıya yükleyin.
Sol bölmeden Güvenlik + ağ> seçin.
Hesap adını ve bağlantı dizesini not edin. Sonraki bir adımda appsettings.json için her iki değere de ihtiyacınız vardır.

Azure Yapay Zeka Arama

Üçüncü bileşen, Azure portalında oluşturabileceğiniz veya Azure kaynaklarınızda mevcut bir arama hizmetini bulabileceğiniz Azure AI Search'dür.

Azure Yapay Zeka Arama için yönetici anahtarını ve URL'sini kopyalama

Arama hizmetinizde kimlik doğrulaması yapmak için hizmet URL'sine ve erişim anahtarına ihtiyacınız vardır. Geçerli bir anahtarın olması, isteği gönderen uygulama ile bunu işleyen hizmet arasında istek başına güven oluşturur.

Azure portalında arama hizmetinize gidin.
Sol bölmeden Genel Bakış'ı seçin.
GIBI görünmesi https://my-service.search.windows.netgereken URL'yi not edin.
Sol bölmeden Ayarlar>Anahtarlar'ı seçin.
Hizmette tam haklar için bir yönetici anahtarını not edin. İş sürekliliğini sağlamak için, birini değiştirmeniz gerektiğinde iki değiştirilebilir yönetici anahtarı sağlanmıştır. nesneleri eklemek, değiştirmek ve silmek için isteklerde iki anahtardan birini kullanabilirsiniz.

Ortamınızı ayarlama

AzureSearchMultipleDataSources.sln Dosyayı Visual Studio'da birden çok veri kaynağı/v11'den açın.
Çözüm Gezgini'nde projeye sağ tıklayın ve Çözüm için NuGet Paketlerini Yönet... seçeneğini belirleyin.
Gözat sekmesinde aşağıdaki paketleri bulun ve yükleyin:
- Azure.Search.Documents (sürüm 11.0 veya üzeri)
- Microsoft.Extensions.Configuration
- Microsoft.Extensions.Configuration.Json

Çözüm Gezgini'nde önceki adımlarda topladığınız bağlantı bilgileriyle appsettings.json dosyasını düzenleyin.

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

Anahtar alanları eşleştir

İçeriği birleştirmek için her iki veri akışının da arama dizinindeki aynı belgeleri hedeflemesi gerekir.

Azure Yapay Zeka Arama'te anahtar alanı her belgeyi benzersiz olarak tanımlar. Her bir arama dizininde, Edm.String türünde tam olarak bir anahtar alanı olmalıdır. Bu anahtar alanı, dizine eklenen bir veri kaynağındaki her belge için mevcut olmalıdır. (Aslında, gereken tek alan bu.)

Birden çok veri kaynağından veri dizini oluştururken, gelen her satır veya belgenin ortak bir belge anahtarı içerdiğinden emin olun. Bu, fiziksel olarak ayrı olan iki kaynak belgedeki verileri birleştirilmiş dizindeki yeni bir arama belgesiyle birleştirmenizi sağlar.

Genellikle dizininiz için anlamlı bir belge anahtarı tanımlamak ve her iki veri kaynağında da var olduğundan emin olmak için bazı ön planlamalar gerektirir. Bu demo gösteriminde, HotelId Azure Cosmos DB'deki her otelin anahtarı, Blob Depolama'daki JSON bloblarında da yer alır.

Azure Yapay Zeka Arama dizin oluşturucuları, dizin oluşturma işlemi sırasında veri alanlarını yeniden adlandırmak ve hatta yeniden biçimlendirmek için alan eşlemelerini kullanabilir, böylece kaynak veriler doğru dizin alanına yönlendirilebilir. Örneğin, Azure Cosmos DB'de otel tanımlayıcısı olarak adlandırılır HotelId, ancak otel odalarının JSON blob dosyalarında otel tanımlayıcısı olarak adlandırılır Id. Program, blob'lardaki Id alanını indeksleyicideki HotelId anahtar alanına eşleyerek bu tutarsızlığı giderir.

Not

Çoğu durumda, bazı dizin oluşturucular tarafından varsayılan olarak oluşturulanlar gibi otomatik olarak oluşturulan belge anahtarları, birleşik dizinler için iyi belge anahtarları oluşturmaz. Genel olarak, veri kaynaklarınızda zaten var olan veya kolayca eklenebilen anlamlı, benzersiz bir anahtar değeri kullanın.

Kodu keşfetme

Veri ve yapılandırma ayarları hazır olduğunda içindeki örnek program AzureSearchMultipleDataSources.sln derlenip çalıştırılmaya hazır olmalıdır.

Bu basit C#/.NET konsol uygulaması aşağıdaki görevleri gerçekleştirir:

C# Hotel sınıfının veri yapısını temel alan ve Address ve Room sınıflarına da başvuran yeni bir dizin oluşturur.
Azure Cosmos DB verilerini dizin alanlarına eşleyen yeni bir veri kaynağı ve dizin oluşturucu oluşturur. Bunların ikisi de Azure Yapay Zeka Arama'teki nesnelerdir.
Azure Cosmos DB'den otel verilerini yüklemek için dizin oluşturucuyu çalıştırır.
İkinci bir veri kaynağı ve JSON blob verilerini dizin alanlarına eşleyen bir dizin oluşturucu oluşturur.
Blob Depolama'dan otel odası verilerini yüklemek için ikinci dizin oluşturucuyu çalıştırır.

Programı çalıştırmadan önce kodu, dizin tanımını ve dizin oluşturucu tanımını incelemek için bir dakikanızı alın. İlgili kod iki dosyada yer alır:

Hotel.cs dizini tanımlayan şemayı içerir.
Program.cs Azure Yapay Zeka Arama dizinini, veri kaynaklarını ve dizin oluşturucuları oluşturan ve birleştirilmiş sonuçları dizine yükleyen işlevler içerir.

Dizin oluşturma

Bu örnek program, Azure Yapay Zeka Arama dizini tanımlamak ve oluşturmak için CreateIndexAsync kullanır. C# veri modeli sınıfından dizin yapısı oluşturmak için FieldBuilder sınıfından yararlanır.

Veri modeli, Address ve Room sınıflarına başvurular da içeren Hotel sınıfı tarafından tanımlanır. FieldBuilder, dizin için karmaşık bir veri yapısı oluşturmak üzere birden çok sınıf tanımında detaya iner. Meta veri etiketleri, her alanın aranabilir veya sıralanabilir olması gibi öznitelikleri tanımlamak için kullanılır.

Bu örneği birden çok kez çalıştırmak istemeniz durumunda, program yenisini oluşturmadan önce aynı ada sahip mevcut tüm dizinleri siler.

Hotel.cs dosyasındaki aşağıdaki kod parçacıkları, önce tek alanları, sonra başka bir veri modeli sınıfı olan Room[] başvurusunu gösterir; Room[] dosyada Room.cs tanımlıdır (gösterilmemektedir).

. . .
[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 Dosyasında SearchIndex, bir ad ve FieldBuilder.Build yöntemiyle oluşturulan bir alan koleksiyonuyla tanımlanır ve aşağıdaki gibi oluşturulur:

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);
}

Azure Cosmos DB veri kaynağı ve dizin oluşturucu oluşturma

Ana program, otel verileri için Azure Cosmos DB veri kaynağını oluşturma mantığını içerir.

İlk olarak, Azure Cosmos DB veritabanı adını bağlantı dizesiyle birleştirir. Ardından bir SearchIndexerDataSourceConnection nesnesi tanımlar.

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);

Veri kaynağı oluşturulduktan sonra program, hotel-rooms-cosmos-indexer adlı bir Azure Cosmos DB dizin oluşturucu ayarlar.

Program, aynı ada sahip tüm mevcut dizin oluşturucuları güncelleştirir ve varolan dizin oluşturucunun üzerine önceki kodun içeriğiyle yazar. Bu örneği birden çok kez çalıştırmak istemeniz durumunda sıfırlama ve çalıştırma eylemlerini de içerir.

Aşağıdaki örnek, dizin oluşturucu için bir zamanlamayı tanımlar, böylece günde bir kez çalışır. Dizin oluşturucunun gelecekte otomatik olarak yeniden çalışmasını istemiyorsanız schedule özelliğini bu çağrıdan kaldırabilirsiniz.

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);
}

Bu örnek, yürütme sırasında oluşabilecek hataları bildirmek için basit bir try-catch bloğu içerir.

Azure Cosmos DB dizin oluşturucu çalıştırıldıktan sonra, arama dizini tam bir örnek otel belgeleri kümesi içerir. Ancak, Azure Cosmos DB veri kaynağı oda ayrıntılarını atladığından, her otelin oda alanı boş bir dizidir. Ardından program, oda verisini yüklemek ve birleştirmek için Blob Depolama'dan çeker.

Blob Depolama veri kaynağı ve dizin oluşturucu oluşturma

Oda ayrıntılarını almak için, program önce tek bir JSON blob dosyaları kümesine başvurmak üzere bir Blob Depolama veri kaynağı ayarlar.

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);

Veri kaynağı oluşturulduktan sonra, program aşağıda gösterildiği gibi adlı hotel-rooms-blob-indexerbir blob dizin oluşturucu ayarlar.

JSON blobları Id yerine HotelId adlı bir anahtar alanı içerir. Kod, dizin oluşturucuya FieldMapping alan değerini dizindeki Id belge anahtarına yönlendirmesini bildirmek için HotelId sınıfını kullanır.

Blob Depolama dizin oluşturucuları bir ayrıştırma modu belirtmek için IndexingParameters kullanabilir. Blobların tek bir belgeyi mi yoksa aynı blob içindeki birden çok belgeyi mi temsil etmelerine bağlı olarak farklı ayrıştırma modları ayarlamanız gerekir. Bu örnekte her blob tek bir JSON belgesini temsil eder, bu nedenle kod ayrıştırma modunu kullanır json . JSON blobları için dizin oluşturucu ayrıştırma parametreleri hakkında daha fazla bilgi için bkz . JSON bloblarını dizinleme.

Bu örnek, dizin oluşturucu için bir zamanlamayı tanımlar ve böylece günde bir kez çalışır. Dizin oluşturucunun gelecekte otomatik olarak yeniden çalışmasını istemiyorsanız schedule özelliğini bu çağrıdan kaldırabilirsiniz.

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);
}

Dizin, Azure Cosmos DB veritabanındaki otel verileriyle zaten dolduruldığından, blob dizin oluşturucu dizindeki mevcut belgeleri güncelleştirir ve oda ayrıntılarını ekler.

Not

Her iki veri kaynağınızda da anahtar olmayan alanlar varsa ve bu alanlardaki veriler eşleşmiyorsa, dizin en son çalıştırılan dizin oluşturucunun değerlerini içerir. Örneğimizde her iki veri kaynağı da bir HotelName alan içerir. Bazı nedenlerden dolayı bu alandaki veriler farklıysa, aynı anahtar değerine sahip belgeler için en HotelName son dizine alınan veri kaynağındaki veriler dizinde depolanan değerdir.

Arama yap

Programı çalıştırdıktan sonra, Azure portalında Arama gezginini kullanarak doldurulmuş arama dizinini keşfedebilirsiniz.

Azure portalında arama hizmetinize gidin.
Sol bölmeden Arama yönetimi>Dizinleri'ni seçin.
Dizin listesinden hotel-rooms-sample öğesini seçin.
Arama gezgini sekmesinde, gibi Luxurybir terim için bir sorgu girin.

Sonuçlarda en az bir belge görmeniz gerekir. Bu belge, Rooms dizisinde oda nesnelerinin bir listesini içermelidir.

Sıfırla ve yeniden çalıştır

Geliştirmenin ilk deneysel aşamalarında tasarım yinelemesi için en pratik yaklaşım, nesneleri Azure Yapay Zeka Arama'ten silmek ve kodunuzun bunları yeniden oluşturmasına izin vermektir. Kaynak adları benzersizdir. Bir nesneyi sildiğinizde, aynı adı kullanarak nesneyi yeniden oluşturabilirsiniz.

Örnek kod mevcut nesneleri denetler ve programı yeniden çalıştırabilmeniz için bunları siler veya güncelleştirir. Dizinleri, dizin oluşturucuları ve veri kaynaklarını silmek için Azure portalını da kullanabilirsiniz.

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, bir projenin sonunda artık ihtiyacınız olmayan kaynakları kaldırmak iyi bir fikirdir. Çalışır durumda bırakılan kaynaklar maliyetlerin artmasına neden olabilir. Kaynakları teker teker silebilir veya tüm kaynak grubunu silerek kaynak kümesinin tamamını kaldırabilirsiniz.

Sol bölmedeki Tüm kaynaklar veya Kaynak grupları bağlantısını kullanarak Azure portalında kaynakları bulabilir ve yönetebilirsiniz.

Sonraki adım

Artık birden çok kaynaktan veri almayı bildiğinize göre, Azure Cosmos DB'den başlayarak dizin oluşturucu yapılandırmasına daha yakından bakın:

NoSQL için Azure Cosmos DB dizin oluşturucu yapılandırma

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-30