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. 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 Azure RBAC (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.
Veri kaynağını, dizini ve dizin oluşturucuyu oluşturmak için bir REST istemcisi.
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.
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=2023-11-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 }
"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"
."Kimlik bilgilerini" bir bağlantı dizesi olarak ayarlayın. Sonraki bölümde desteklenen biçimler açıklanmaktadır.
"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.
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.
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.
Tam erişim bağlantı dizesi |
---|
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id> " }` |
Sol gezinti bölmesinde Anahtarlar'ı seçerek Azure portalındaki Azure Cosmos DB hesap sayfasından bağlantı dizesi alabilirsiniz. Yalnızca bir anahtar değil tam bir bağlantı dizesi seçtiğinizden emin olun. |
Yönetilen kimlik bağlantı dizesi |
---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=[identity-auth-type])" } |
Bu bağlantı dizesi hesap anahtarı gerektirmez, ancak yönetilen kimlik kullanarak bağlanabilen bir arama hizmetiniz olmalıdır. SQL API'sini hedefleyen bağlantılar için bağlantı dizesi atlayabilirsinizApiKind . hakkında ApiKind IdentityAuthType daha fazla bilgi için bkz. Yönetilen kimlik kullanarak Azure Cosmos DB veritabanına dizin oluşturucu bağlantısı kurma. |
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.
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=2023-11-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 } ] }
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.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
JSON veri türleri | Azure AI Search alan türleri |
---|---|
Boole | Edm.Boolean, Edm.String |
Tamsayı gibi görünen sayılar | Edm.Int32, Edm.Int64, Edm.String |
Kayan noktalar gibi görünen sayılar | Edm.Double, Edm.String |
String | Edm.String |
["a", "b", "c"] gibi ilkel tür dizileri | Collection(Edm.String) |
Tarih gibi görünen dizeler | Edm.DateTimeOffset, Edm.String |
{ "type": "Point", "coordinates": [long, lat] } gibi GeoJSON nesneleri | Edm.GeographyPoint |
Diğer JSON nesneleri | Yok |
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.
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=2023-11-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 }
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 Dizin Oluşturucu Durumunu Al isteği gönderin:
GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
Content-Type: application/json
api-key: [admin key]
Yanıt, durumu ve işlenen öğe sayısını içerir. Aşağıdaki örneğe benzer görünmelidir:
{
"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"
},
Not
Azure Cosmos DB'nizdeki bir null
alana değer atadığınızda, AI Search dizin oluşturucu ile eksik alan değerini ayırt null
edemez. Bu nedenle, dizindeki bir alan boşsa, bu değişiklik veritabanınızda özel olarak null
yapılmış olsa bile bir değerle değiştirilmez.
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 _ts
sı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=2023-11-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:
Geri Bildirim
https://aka.ms/ContentUserFeedback.
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz.Gönderin ve geri bildirimi görüntüleyin