Azure AI Search'teki sorgular için NoSQL için Azure Cosmos DB'den dizin verileri

Bu makalede, NoSQL için Azure Cosmos DB'den içerik içeri aktaran ve Azure AI Search'te aranabilir hale getiren bir dizin oluşturucu yapılandırmayı öğrenin.

Bu makale , Cosmos DB'ye özgü bilgilerle dizin oluşturucu oluşturma makalesini tamamlar. Azure portalını ve REST API'lerini kullanarak tüm dizin oluşturucular için ortak olan üç parçalı bir iş akışını gösterir: veri kaynağı oluşturma, dizin oluşturma, dizin oluşturucu oluşturma. Dizin Oluşturucu Oluştur isteğini gönderdiğinizde veri ayıklama gerçekleşir.

Terminoloji kafa karıştırıcı olabileceği için Azure Cosmos DB dizin oluşturma ve Azure AI Search dizin oluşturma işlemlerinin farklı işlemler olduğunu belirtmek gerekir. Azure AI Search'te dizin oluşturma, arama hizmetinizde bir arama dizini oluşturur ve yükler.

Önkoşullar

• Azure Cosmos DB hesabı, veritabanı, kapsayıcı ve öğeler. Daha düşük gecikme süresi ve bant genişliği ücretlerini önlemek için hem Azure AI Search hem de Azure Cosmos DB için aynı bölgeyi kullanın.

• Azure Cosmos DB koleksiyonunda Tutarlı olarak ayarlanmış bir otomatik dizin oluşturma ilkesi. Bu, varsayılan yapılandırmadır. Gecikmeli dizin oluşturma önerilmez ve eksik verilere neden olabilir.

• Okuma izinleri. "Tam erişim" bağlantı dizesi içeriğe erişim sağlayan bir anahtar içerir, ancak kimlikler (Microsoft Entra ID) kullanıyorsanız arama hizmeti yönetilen kimliğine hem Cosmos DB Hesap Okuyucusu Rolü hem de Cosmos DB Yerleşik Veri Okuyucusu Rolü atandığından emin olun.

Bu makaledeki örnekleri inceleyebilmek için Azure portalına veya REST istemcisine ihtiyacınız vardır. Azure portalı kullanıyorsanız tüm genel ağlara erişimin etkinleştirildiğinden emin olun. Cosmos DB dizin oluşturucu oluşturmaya yönelik diğer yaklaşımlar arasında Azure SDK'ları bulunur.

Örnek verilerle deneme

Test amacıyla Cosmos DB'de kapsayıcı ve veritabanı oluşturmak için bu yönergeleri kullanın.

1. Cosmos DB'de örnek otel veri kümesinin bir alt kümesini içeren bir kapsayıcı oluşturmak için GitHub'dan HotelsData_toCosmosDB.JSON indirin.

2. Azure portalında oturum açın ve Cosmos DB'de bir hesap, veritabanı ve kapsayıcı oluşturun.

3. Cosmos DB'de yeni kapsayıcı için Veri Gezgini seçin ve aşağıdaki değerleri sağlayın.

   Özellik	Değer
   Veritabanı	Özel programlamayı kullanmadan, yeni
   Veritabanı Kimliği	hotelsdb
   Aktarım hızını kapsayıcılar arasında paylaşma	Seçme
   Kapsayıcı Kimliği	oteller
   Bölüm anahtarı	/HotelId
   Kapsayıcı aktarım hızı (otomatik ölçeklendirme)	Otomatik Ölçeklendirme
   Kapsayıcı Maksimum RU/sn	1000

4. Veri Gezgini hotelsdb ve *hotels" alanlarını genişletin ve ardından Öğeler'i seçin.

5. Öğeyi Karşıya Yükle'yi ve ardından GitHub'dan indirdiğiniz HotelsData_toCosmosDB.JSON dosyasını seçin.

6. Öğeler'e sağ tıklayın ve Yeni SQL sorgusu'yu seçin. Varsayılan sorgudur SELECT * FROM c.

7. Sorguyu çalıştırmak ve sonuçları görüntülemek için Sorguyu yürüt'ü seçin. 50 otel belgeniz olmalıdır.

Artık kapsayıcınız olduğuna göre, verilerinizi dizine almak için Azure portalını, REST istemcisini veya Azure SDK'sını kullanabilirsiniz.

Açıklama alanı en ayrıntılı içeriği sağlar. Tam metin araması ve isteğe bağlı vektör sorguları için bu alanı hedeflemeniz gerekir.

Azure portal’ı kullanma

SQL veritabanı tablosundan veya görünümünden dizin oluşturmayı otomatikleştirmek için Verileri içeri aktarma sihirbazını veya Verileri içeri aktarma ve vektörleştirme sihirbazını kullanabilirsiniz. Veri kaynağı yapılandırması her iki sihirbaz için de benzerdir.

1. Sihirbazı başlatın.

2. Verilerinize bağlanın sayfasında veri kaynağı türünün Azure Cosmos DB veya NoSQL hesabı olduğunu seçin veya doğrulayın.

   Veri kaynağı adı, Azure AI Search'teki veri kaynağı bağlantı nesnesine başvurur. Vektör sihirbazını kullanırsanız, veri kaynağı adınız sihirbaz iş akışının sonunda belirtilen özel bir ön ek kullanılarak otomatik olarak oluşturulur.

3. Veritabanı adını ve koleksiyonunu belirtin. Sorgu isteğe bağlıdır. Hiyerarşik verileriniz varsa ve belirli bir dilimi içeri aktarmak istiyorsanız kullanışlıdır.

4. Yönetilen kimlik veya yerleşik API anahtarı gibi bir kimlik doğrulama yöntemi belirtin. Yönetilen kimlik bağlantısı belirtmezseniz Azure portalı anahtarı kullanır.

   Azure AI Search'i yönetilen kimlik kullanacak şekilde yapılandırıp Cosmos DB'de Cosmos DB Hesap Okuyucusu ve Cosmos DB Yerleşik Veri Okuyucusu izinleri veren bir rol ataması oluşturursanız, dizin oluşturucunuz Microsoft Entra Kimliği ve rolleri kullanarak Cosmos DB'ye bağlanabilir.

5. Verileri içeri aktarma ve vektörleştirme sihirbazı için değişiklik ve silme izleme seçeneklerini belirtebilirsiniz.

   Değişiklik algılama , bir _ts alan (zaman damgası) aracılığıyla varsayılan olarak desteklenir. Örnek verilerle deneme bölümünde açıklanan yaklaşımı kullanarak içerik yüklerseniz, koleksiyon bir _ts alanla oluşturulur.

   Silme algılaması , koleksiyonda geçici silme bayrağı olarak kullanılabilecek önceden var olan bir üst düzey alanınız olmasını gerektirir. Bir Boole alanı olmalıdır (isDeleted olarak adlandırabilirsiniz). Geçici olarak silinen değer olarak belirtin true . Arama dizininde, alınabilir ve filtrelenebilir olarak ayarlanmış IsDeleted adlı ilgili bir arama alanı ekleyin.

6. Sihirbazı tamamlamak için kalan adımlarla devam edin:

   • Hızlı Başlangıç: Veri içeri aktarma sihirbazı

   • Hızlı Başlangıç: Verileri içeri aktarma ve vektörleştirme sihirbazı

REST API’leri kullanma

Bu bölümde veri kaynağı, dizin ve dizin oluşturucu oluşturan REST API çağrıları gösterilmektedir.

Veri kaynağını tanımlama

Veri kaynağı tanımı, verilerdeki değişiklikleri tanımlamak için dizine eklenecek verileri, kimlik bilgilerini ve ilkeleri belirtir. Veri kaynağı, birden çok dizin oluşturucu tarafından kullanılabilen bağımsız bir kaynaktır.

1. Tanımını ayarlamak için bir veri kaynağı oluşturun veya güncelleştirin:

   POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
   Content-Type: application/json
   api-key: [Search service admin key]
   {
       "name": "[my-cosmosdb-ds]",
       "type": "cosmosdb",
       "credentials": {
         "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
       },
       "container": {
         "name": "[my-cosmos-db-collection]",
         "query": null
       },
       "dataChangeDetectionPolicy": {
         "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
       "  highWaterMarkColumnName": "_ts"
       },
       "dataDeletionDetectionPolicy": null,
       "encryptionKey": null,
       "identity": null
   }
   

2. "type" değerini (gerekli) olarak "cosmosdb" ayarlayın. Eski bir Arama API'sinin 2017-11-11 sürümünü kullanıyorsanız, "tür" söz dizimi şeklindedir "documentdb". Aksi takdirde, 2019-05-06 ve üzeri için kullanın "cosmosdb".

3. "Kimlik bilgilerini" bir bağlantı dizesi olarak ayarlayın. Sonraki bölümde desteklenen biçimler açıklanmaktadır.

4. "kapsayıcı" öğesini koleksiyon olarak ayarlayın. "name" özelliği gereklidir ve dizine eklenecek veritabanı koleksiyonunun kimliğini belirtir. "query" özelliği isteğe bağlıdır. Rastgele bir JSON belgesini Azure AI Search'in dizine ekleyebilecekleri düz bir şemada düzleştirmek için kullanın.

5. Veriler geçiciyse ve dizin oluşturucunun sonraki çalıştırmalarda yalnızca yeni ve güncelleştirilmiş öğeleri almasını istiyorsanız "dataChangeDetectionPolicy" değerini ayarlayın.

6. Kaynak öğe silindiğinde arama belgelerini bir arama dizininden kaldırmak istiyorsanız "dataDeletionDetectionPolicy" değerini ayarlayın.

Desteklenen kimlik bilgileri ve bağlantı dizesi

Dizin oluşturucular aşağıdaki bağlantıları kullanarak bir koleksiyona bağlanabilir.

Uç nokta URL'sinde bağlantı noktası numaralarından kaçının. Bağlantı noktası numarasını eklerseniz bağlantı başarısız olur.

Dizine alınan verileri şekillendirmek için sorguları kullanma

"container" altındaki "query" özelliğinde iç içe özellikleri veya dizileri düzleştirmeye, JSON özelliklerini yansıtmaya ve dizine eklenecek verileri filtrelemeye yönelik bir SQL sorgusu belirtebilirsiniz.

Örnek belge:

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

Filtre sorgusu:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

Düzleştirme sorgusu:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Projeksiyon sorgusu:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Dizi düzleştirme sorgusu:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Desteklenmeyen sorgular (DISTINCT ve GROUP BY)

DISTINCT anahtar sözcüğünü veya GROUP BY yan tümcesini kullanan sorgular desteklenmez. Azure AI Search, sorgunun sonuçlarını tam olarak listelemek için SQL sorgu sayfalandırmasına dayanır. DISTINCT anahtar sözcüğü veya GROUP BY yan tümceleri sonuçları sayfalandırmak için kullanılan devamlılık belirteçleriyle uyumlu değildir.

Desteklenmeyen sorgu örnekleri:

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Azure Cosmos DB' nin ORDER BY yan tümcesini kullanarak DISTINCT anahtar sözcüğüyle SQL sorgu sayfalandırmasını desteklemek için bir geçici çözümü olsa da, Azure AI Search ile uyumlu değildir. Sorgu tek bir JSON değeri döndürürken Azure AI Search bir JSON nesnesi bekler.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

Dizine arama alanları ekleme

Arama dizininde, kaynak JSON belgelerini veya özel sorgu projeksiyonunuzun çıkışını kabul etmek için alanlar ekleyin. Arama dizini şemasının kaynak verilerle uyumlu olduğundan emin olun. Azure Cosmos DB'deki içerik için arama dizini şemanız veri kaynağınızdaki Azure Cosmos DB öğelerine karşılık gelir.

1. Verileri depolayan arama alanlarını tanımlamak için bir dizin oluşturun veya güncelleştirin:

   POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
   Content-Type: application/json
   api-key: [Search service admin key]
   {
       "name": "mysearchindex",
       "fields": [{
           "name": "rid",
           "type": "Edm.String",
           "key": true,
           "searchable": false
       }, 
       {
           "name": "description",
           "type": "Edm.String",
           "filterable": false,
           "searchable": true,
           "sortable": false,
           "facetable": false,
           "suggestions": true
       }
     ]
   }
   

2. Belge anahtarı alanı oluşturma ("anahtar": true). Bölümlenmiş koleksiyonlar için varsayılan belge anahtarı Azure rid Cosmos DB _rid özelliğidir ve alan adları alt çizgi karakteriyle başlayamaz. Ayrıca Azure Cosmos DB _rid değerleri, Azure AI Arama anahtarlarında geçersiz karakterler içerir. Bu nedenle değerler _rid Base64 ile kodlanmıştır.

3. Daha fazla aranabilir içerik için daha fazla alan oluşturun. Ayrıntılar için bkz . Dizin oluşturma.

Eşleme veri türleri

NoSQL için Azure Cosmos DB dizin oluşturucusunu yapılandırma ve çalıştırma

Dizin ve veri kaynağı oluşturulduktan sonra dizin oluşturucuyu oluşturmaya hazır olursunuz. Dizin oluşturucu yapılandırması, çalışma zamanı davranışlarını denetleen girişleri, parametreleri ve özellikleri belirtir.

1. Dizin oluşturucuya bir ad verip veri kaynağına ve hedef dizine başvurarak dizin oluşturucu oluşturun veya güncelleştirin:

   POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
   Content-Type: application/json
   api-key: [search service admin key]
   {
       "name" : "[my-cosmosdb-indexer]",
       "dataSourceName" : "[my-cosmosdb-ds]",
       "targetIndexName" : "[my-search-index]",
       "disabled": null,
       "schedule": null,
       "parameters": {
           "batchSize": null,
           "maxFailedItems": 0,
           "maxFailedItemsPerBatch": 0,
           "base64EncodeKeys": false,
           "configuration": {}
           },
       "fieldMappings": [],
       "encryptionKey": null
   }
   

2. Alan adında veya türünde farklılıklar varsa veya arama dizininde bir kaynak alanın birden çok sürümüne ihtiyacınız varsa alan eşlemelerini belirtin.

3. Diğer özellikler hakkında daha fazla bilgi için bkz . Dizin oluşturucu oluşturma.

Dizin oluşturucu oluşturulduğunda otomatik olarak çalışır. "Devre dışı" ayarını true olarak ayarlayarak bunu önleyebilirsiniz. Dizin oluşturucu yürütmesini denetlemek için isteğe bağlı olarak bir dizin oluşturucu çalıştırın veya zamanlamaya yerleştirin.

Dizin oluşturucu durumunu denetleme

Dizin oluşturucu durumunu ve yürütme geçmişini izlemek için Azure portalında dizin oluşturucu yürütme geçmişini denetleyin veya Dizin Oluşturucu Durumunu Al RESTIRequest gönderin

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-01
  Content-Type: application/json  
  api-key: [admin key]

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

Yürütme geçmişi, en son tamamlanan yürütmelerin en son 50'sini içerir ve en son yürütme önce gelecek şekilde ters kronolojik sırada sıralanır.

Yeni ve değiştirilmiş belgelerin dizinini oluşturma

Dizin oluşturucu bir arama dizinini tam olarak doldurduktan sonra, sonraki dizin oluşturucu çalıştırmalarının veritabanınızdaki yalnızca yeni ve değiştirilmiş belgeleri artımlı olarak dizinlemesini isteyebilirsiniz.

Artımlı dizin oluşturmayı etkinleştirmek için veri kaynağı tanımınızda "dataChangeDetectionPolicy" özelliğini ayarlayın. Bu özellik, dizin oluşturucuya verilerinizde hangi değişiklik izleme mekanizmasının kullanıldığını bildirir.

Azure Cosmos DB dizin oluşturucuları için desteklenen tek ilke, Azure Cosmos DB tarafından sağlanan kullanım (zaman damgası) özelliğidir HighWaterMarkChangeDetectionPolicy _ts .

Aşağıdaki örnekte, değişiklik algılama ilkesine sahip bir veri kaynağı tanımı gösterilmektedir:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

Artımlı dizin oluşturma ve özel sorgular

Belgeleri almak için özel bir sorgu kullanıyorsanız, sorgunun sonuçları sütuna göre sıraladığınızdan _ts emin olun. Bu, Azure AI Search'ün hataların varlığında artımlı ilerleme sağlamak için kullandığı düzenli denetim işaretlerini etkinleştirir.

Bazı durumlarda, sorgunuz bir ORDER BY [collection alias]._ts yan tümce içerse bile Azure AI Search sorgunun tarafından _tssıralandığını çıkaramayabilir. Yapılandırma özelliğini ayarlayarak Azure AI Search'e sonuçların assumeOrderByHighWaterMarkColumn sıralandığını belirtebilirsiniz.

Bu ipucunu belirtmek için dizin oluşturucu tanımınızı aşağıdaki gibi oluşturun veya güncelleştirin:

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
} 

Silinen belgelerin dizinini oluşturma

Satırlar koleksiyondan silindiğinde, normalde bu satırları da arama dizininden silmek istersiniz. Veri silme algılama ilkesinin amacı, silinen veri öğelerini verimli bir şekilde tanımlamaktır. Şu anda desteklenen tek ilke Soft Delete , veri kaynağı tanımında aşağıdaki gibi belirtilen ilkedir (silme işlemi bir tür bayrakla işaretlenir):

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

Özel sorgu kullanıyorsanız, tarafından başvuruda bulunılan softDeleteColumnName özelliğin sorgu tarafından yansıtıldığından emin olun.

, softDeleteColumnName dizinde en üst düzey bir alan olmalıdır. karmaşık veri türleri softDeleteColumnName içinde iç içe alanları kullanma desteklenmez.

Aşağıdaki örnek geçici silme ilkesine sahip bir veri kaynağı oluşturur:

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

.NET’i kullanma

SQL API protokolü aracılığıyla erişilen veriler için dizin oluşturucularla otomatikleştirmek için .NET SDK'sını kullanabilirsiniz. Kavramları, iş akışını ve gereksinimleri öğrenmek için önceki REST API bölümlerini gözden geçirmenizi öneririz. Daha sonra yönetilen kodda JSON dizin oluşturucu uygulamak için aşağıdaki .NET API başvuru belgelerine başvurabilirsiniz:

• azure.search.documents.indexes.models.searchindexerdatasourceconnection
• azure.search.documents.indexes.models.searchindexerdatasourcetype
• azure.search.documents.indexes.models.searchindex
• azure.search.documents.indexes.models.searchindexer

Sonraki adımlar

Artık dizin oluşturucuyu çalıştırmayı, durumu izlemeyi veya dizin oluşturucu yürütmeyi zamanlamayı denetleyebilirsiniz. Aşağıdaki makaleler Azure Cosmos DB'den içerik çeken dizin oluşturucular için geçerlidir:

• Yönetilen kimlik kullanarak Azure Cosmos DB veritabanına dizin oluşturucu bağlantısı kurma
• Büyük veri kümelerini dizine ekleme
• Azure ağ güvenlik özellikleri tarafından korunan içeriğe dizin oluşturucu erişimi