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

Makale
09/01/2024

Azure AI Search birden çok veri kaynağındaki verileri tek bir birleştirilmiş arama dizinine aktarabilir, analiz edebilir ve dizinleyebilir.

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

Bu öğreticide aşağıdaki görevleri gerçekleştireceksiniz:

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

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

Genel bakış

Bu öğreticide, birden çok dizin oluşturucu oluşturmak ve çalıştırmak için Azure.Search.Documents kullanılır. Bu öğreticide, tek bir arama dizinini doldurmak için her ikisinden de çeken bir dizin oluşturucu yapılandırabilmek için iki Azure veri kaynağı ayarlayacaksınız. Birleştirmeyi desteklemek için iki veri kümesinin ortak bir değeri olmalıdır. Bu örnekte 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 depolamadan 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

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 öğreticide hepsinden birer tane oluşturulur. Başlamadan önce, hizmetinizde yeni kaynakları kabul etmek için yer olduğundan emin olun.

1 - Hizmet oluşturma

Bu öğreticide dizin oluşturma ve sorgular için Azure AI Search, bir 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 tanımlayan 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 yüklenecek yedi ayrı JSON dosyası olarak sağlanır.

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

Azure portalında oturum açın ve Azure Cosmos DB hesabına Genel Bakış sayfanızda gezinin.
Veri Gezgini'ı ve ardından Yeni Veritabanı'ı seçin.
hotel-rooms-db adını girin. Kalan ayarlar için varsayılan değerleri kabul edin.
Yeni bir kapsayıcı oluşturun. Yeni oluşturduğunuz mevcut veritabanını kullanın. Kapsayıcı adı için oteller girin ve Bölüm anahtarı için /HotelId kullanın.
Oteller altındaki Öğeler'i ve ardından komut çubuğunda Öğeyi Karşıya Yükle'yi seçin. Adresine gidin ve proje klasöründe cosmosdb/HotelsDataSubset_CosmosDb.json dosyasını seçin.
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.
Anahtarlar sayfasından Not Defteri'ne bir bağlantı dizesi kopyalayın. Sonraki bir adımda appsettings.json için bu değere ihtiyacınız olacak. Önerilen veritabanı adını "hotel-rooms-db" kullanmadıysanız veritabanı adını da kopyalayın.

Azure Blob Storage

Azure portalında oturum açın, Azure depolama hesabınıza gidin, Bloblar'ı ve ardından + Kapsayıcı'yı seçin.
Örnek otel odası JSON dosyalarını depolamak için hotel-rooms adlı bir blob kapsayıcısı oluşturun. Genel Erişim Düzeyi'ni geçerli değerlerinden herhangi birine ayarlayabilirsiniz.
Kapsayıcı oluşturulduktan sonra kapsayıcıyı açın ve komut çubuğunda Karşıya Yükle'yi seçin. Örnek dosyaları içeren klasöre gidin. Tümünü seçin ve ardından Karşıya Yükle'yi seçin.
Erişim Anahtarları sayfasındaki depolama hesabı adını ve bağlantı dizesi Not Defteri'ne kopyalayın. Sonraki bir adımda appsettings.json için her iki değere de ihtiyacınız olacak.

Azure Yapay Zeka Arama

Üçüncü bileşen, portalda oluşturabileceğiniz veya Azure kaynaklarınızda mevcut bir arama hizmetini bulabileceğiniz Azure AI Search bileşenidir.

Azure AI Search için yönetici api 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.

Azure portalında oturum açın ve arama hizmetine Genel Bakış sayfanızda URL'yi alın. Örnek uç nokta https://mydemo.search.windows.net şeklinde görünebilir.
Ayarlar>Anahtarları'nda, hizmet üzerinde tam haklar için bir yönetici anahtarı alın. Bir tane yuvarlamanız gerektiğinde iş sürekliliği için sağlanan iki değiştirilebilir yönetici anahtarı vardır. Nesneleri ekleme, değiştirme ve silme isteklerinde birincil veya ikincil anahtarı kullanabilirsiniz.

İstek başına geçerli bir anahtara sahip olmak, isteği gönderen uygulama ve bunu işleyen hizmet arasında güven oluşturur.

2 - Ortamınızı ayarlama

Visual Studio'yu başlatın ve Araçlar menüsünde NuGet Paket Yöneticisi'ı seçin ve ardından Çözüm için NuGet Paketlerini Yönet....
Gözat sekmesinde Azure.Search.Documents (sürüm 11.0 veya üzeri) bulun ve yükleyin.
Microsoft.Extensions.Configuration ve Microsoft.Extensions.Configuration.Json NuGet paketlerini arayın ve bunları da yükleyin.
/v11/AzureSearchMultipleDataSources.sln çözüm dosyasını açın.

Çözüm Gezgini'da, bağlantı bilgileri eklemek için appsettings.json dosyasını düzenleyin.

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

İlk iki girdi, arama hizmetinin URL'si ve yönetici anahtarlarıdır. Tam uç noktayı kullanın, örneğin: https://mydemo.search.windows.net.

Sonraki girişler, Azure Blob Depolama ve Azure Cosmos DB veri kaynakları için hesap adlarını ve bağlantı dizesi bilgilerini belirtir.

3 - Anahtar alanlarını eşleme

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

Azure AI Search'te anahtar alanı her belgeyi benzersiz olarak tanımlar. Her arama dizininde türünde Edm.Stringtam 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, her gelen satır veya belgenin fiziksel olarak ayrı olan iki kaynak belgedeki verileri birleştirilmiş dizindeki yeni bir arama belgesiyle birleştirmek için ortak bir belge anahtarı içerdiğinden emin olun.

Genellikle dizininiz için anlamlı bir belge anahtarı tanımlamak ve her iki veri kaynağında da var olduğundan emin olmak için önceden planlama yapılması gerekir. Bu tanıtımda, HotelId Azure Cosmos DB'deki her otelin anahtarı Blob depolamadaki JSON bloblarında da bulunur.

Azure AI Search 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, alanı bloblardan HotelId dizin oluşturucudaki anahtar alanına eşleyerek Id bu tutarsızlığı işler.

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 kullanmak isteyeceksiniz.

4 - Kodu keşfetme

Veri ve yapılandırma ayarları gerçekleştikten sonra ,/v11/AzureSearchMultipleDataSources.sln içindeki örnek program derlemeye ve çalıştırmaya 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 yeni bir dizin oluşturur (Adres ve Oda sınıflarına da başvurur).
Azure Cosmos DB verilerini dizin alanlarına eşleyen yeni bir veri kaynağı ve dizin oluşturucu oluşturur. Bunların ikisi de Azure AI Search'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 depolamadan Oda verilerini yüklemek için ikinci dizin oluşturucuyu çalıştırır.

Programı çalıştırmadan önce kodu ve bu örneğe ilişkin dizin ve dizin oluşturucu tanımlarını incelemek için bir dakika bekleyin. İlgili kod iki dosyada yer alır:

Hotel.cs dizini tanımlayan şemayı içerir
Program.cs, Azure AI Search 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 AI Search 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ında tek alanlar ve ardından başka bir veri modeli sınıfı olan Room[] başvurusu gösterilir ve bu da Room.cs dosyasında tanımlanır (gösterilmez).

. . .
[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, yöntemi tarafından FieldBuilder.Build oluşturulan bir ad ve 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

Ardından 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ı dizesi 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 yukarıdaki kodun içeriğiyle var olan dizin oluşturucunun üzerine 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şturucusu ç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 dizi olacaktır. Ardından program, oda verilerini yüklemek ve birleştirmek için Blob depolama alanından ç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 hotel-rooms-blob-indexer adlı bir blob dizin oluşturucu ayarlar.

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

Blob depolama dizin oluşturucuları, ayrıştırma modunu belirtmek için IndexingParameters kullanabilir. Blobların tek bir belgeyi mi yoksa aynı blob içinde 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 zamanlama 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.

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 doldurulmuş olduğundan, 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 son dizine alınan veri kaynağındaki HotelName verileri dizinde depolanan değer olacaktır.

5 - Arama

Program çalıştırıldıktan sonra portaldaki Arama gezginini kullanarak doldurulmuş arama dizinini inceleyebilirsiniz.

Azure portalında arama hizmetine Genel Bakış sayfasını açın ve Dizinler listesinde hotel-rooms-sample dizinini bulun.

Azure AI Search dizinlerinin listesi

Listedeki hotel-rooms-sample dizinini seçin. Dizin için bir Arama Gezgini arabirimi görürsünüz. "Luxury" gibi bir terim için sorgu girin. Sonuçlarda en az bir belge görmeniz ve bu belgenin oda dizisindeki oda nesnelerinin listesini göstermesi gerekir.

Sıfırlama ve yeniden çalıştırma

Geliştirmenin ilk deneysel aşamalarında tasarım yinelemesi için en pratik yaklaşım, nesneleri Azure AI Search'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 portalı 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 gezinti bölmesindeki Tüm kaynaklar veya Kaynak grupları bağlantısını kullanarak kaynakları portalda bulabilir ve yönetebilirsiniz.

Sonraki adımlar

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

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

Aracılığıyla paylaş