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

Makale
01/18/2024

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 atlayabilirsiniz`ApiKind`. hakkında `ApiKindIdentityAuthType` 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
}

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.
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"
},

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=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:

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: