重要
根据补充使用条款,MongoDB API 支持当前以公共预览版提供。 目前没有 SDK 支持。
本文将介绍如何配置索引器,该索引器从 Azure Cosmos DB for MongoDB 导入内容,并使内容在 Azure AI 搜索中可供搜索。
本文是对创建索引器的补充,其中包含特定于 Cosmos DB 的信息。 它使用 REST API 演示所有索引器通用的三部分工作流:创建数据源、创建索引、创建索引器。 提交“创建索引器”请求时,将提取数据。
由于术语可能会造成混淆,特此提示,Azure Cosmos DB 索引编制和 Azure AI 搜索索引编制属于不同的操作。 在 Azure AI 搜索中编制索引可在搜索服务中创建并加载搜索索引。
先决条件
注册预览版以提供方案反馈。 在提交表单后,你可以自动访问该功能。
Azure Cosmos DB 帐户、数据库、集合和文档。 对 Azure AI 搜索和 Azure Cosmos DB 使用同一个区域,以降低延迟并避免带宽费用。
针对 Azure Cosmos DB 集合的自动索引策略,设置为“一致”。 这是默认配置。 建议不要使用惰性索引编制,这可能会导致丢失数据。
读取权限。 “完全访问权限”连接字符串包含授予对内容的访问权限的密钥,但如果使用的是 Azure 角色,请确保搜索服务托管标识具有“Cosmos DB 帐户读者角色”权限。
一个 REST 客户端,用于创建数据源、索引和索引器。
限制
下面是此功能的相关限制:
指定数据集不支持自定义查询。
列名
_ts
是保留字。 如果需要此字段,请考虑用于填充索引的替代解决方案。MongoDB 属性
$ref
是保留字。 如果在你的 MongoDB 集合中需要此字段,请考虑使用替代解决方案来填充索引。
作为此连接器的替代方法,如果你的方案具有任何这些要求,则可以使用推送 API/SDK,或考虑使用将 Azure AI 搜索索引作为接收器的 Azure 数据工厂。
定义数据源
数据源定义指定要编制索引的数据、凭据和用于标识数据更改的策略。 数据源定义为独立的资源,以便它可以被多个索引器使用。
对于此调用,请指定预览版 REST API。 可以使用 2020-06-30-preview 或更高版本来创建通过 MongoDB API 连接的数据源。 建议使用最新的预览版 REST API。
创建或更新数据源以设置其定义:
POST https://[service name].search.azure.cn/datasources?api-version=2024-05-01-preview Content-Type: application/json api-key: [Search service admin key] { "name": "[my-cosmosdb-mongodb-ds]", "type": "cosmosdb", "credentials": { "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.cn;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb;" }, "container": { "name": "[cosmos-db-collection]", "query": null }, "dataChangeDetectionPolicy": { "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName": "_ts" }, "dataDeletionDetectionPolicy": null, "encryptionKey": null, "identity": null }
将 "type" 设置为
"cosmosdb"
(必需)。将“凭据”设置为连接字符串。 下一部分介绍受支持的格式。
将“容器”设置为集合。 “名称”属性是必填的,它指定要编制索引的数据库集合的 ID。 对于 Azure Cosmos DB for MongoDB,不支持“查询”。
如果数据经常变动,且你希望索引器在后续运行时只获取新项和更新的项,则设置“dataChangeDetectionPolicy”。
如果要在删除源项时从搜索索引中删除搜索文档,则设置“dataDeletionDetectionPolicy”。
受支持的凭据和连接字符串
索引器可以使用以下连接连接到集合。 对于面向 MongoDB API 的连接,请确保在连接字符串中包含“ApiKind”。
避免在终结点 URL 中包含端口号。 如果包含端口号,连接将失败。
完全访问权限连接字符串 |
---|
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.cn;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" } |
可通过在左侧导航窗格中选择“连接字符串”,从 Azure 门户的 Azure Cosmos DB 帐户页中获取 Cosmos DB 身份验证密钥。 请确保复制主密码并用其替换 Cosmos DB 身份验证密钥值。 |
托管标识连接字符串 |
---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" } |
此连接字符串不需要帐户密钥,但你之前必须已将搜索服务配置为使用托管标识进行连接,并已创建一个授予“Cosmos DB 帐户读者角色”权限的角色分配。 有关详细信息,请参阅使用托管标识设置与 Azure Cosmos DB 数据库的索引器连接。 |
将搜索字段添加到索引
在搜索索引中,添加字段以接受源 JSON 文档或自定义查询投影的输出。 确保搜索索引架构与源数据兼容。 对于 Azure Cosmos DB 中的内容,搜索索引架构应对应于数据源中的 Azure Cosmos DB 项。
创建或更新索引以定义将存储数据的搜索字段:
POST https://[service name].search.azure.cn/indexes?api-version=2024-05-01-preview Content-Type: application/json api-key: [Search service admin key] { "name": "mysearchindex", "fields": [{ "name": "doc_id", "type": "Edm.String", "key": true, "retrievable": true, "searchable": false }, { "name": "description", "type": "Edm.String", "filterable": false, "searchable": true, "sortable": false, "facetable": false, "suggestions": true }] }
创建文档键字段 ("key": true)。 对于基于 MongoDB 集合的搜索索引,文档键可以是“doc_id”、“rid”或其他包含唯一值的字符串字段。 只要两侧的字段名称和数据类型相同,就不需要字段映射。
“doc_id”表示对象标识符的“_id”。 如果在索引中指定“doc_id”字段,索引器将使用对象标识符的值填充该字段。
“rid”是 Azure Cosmos DB 中的系统属性。 如果在索引中指定“rid”字段,索引器将使用“rid”属性的 base64 编码值填充该字段。
对于任何其他字段,搜索字段的名称应与集合中定义的名称相同。
创建其他字段,以获得更多可搜索的内容。 有关详细信息,请参阅创建索引。
映射数据类型
JSON 数据类型 | Azure AI 搜索字段类型 |
---|---|
Bool | Edm.Boolean、Edm.String |
类似于整数的数字 | Edm.Int32、Edm.Int64、Edm.String |
类似于浮点的数字 | Edm.Double、Edm.String |
String | Edm.String |
基元类型的数组,如 ["a", "b", "c"] | 集合 (Edm.String) |
类似于日期的字符串 | Edm.DateTimeOffset、Edm.String |
GeoJSON 对象,如 { "type": "Point", "coordinates": [long, lat] } | Edm.GeographyPoint |
其他 JSON 对象 | 空值 |
配置并运行 Azure Cosmos DB for MongoDB 索引器
创建索引和数据源后,便可以准备创建索引器。 索引器配置指定控制运行时行为的输入、参数和属性。
通过为索引器命名并引用数据源和目标索引来创建或更新索引器:
POST https://[service name].search.azure.cn/indexers?api-version=2024-05-01-preview Content-Type: application/json api-key: [search service admin key] { "name" : "[my-cosmosdb-indexer]", "dataSourceName" : "[my-cosmosdb-mongodb-ds]", "targetIndexName" : "[my-search-index]", "disabled": null, "schedule": null, "parameters": { "batchSize": null, "maxFailedItems": 0, "maxFailedItemsPerBatch": 0, "base64EncodeKeys": false, "configuration": {} }, "fieldMappings": [], "encryptionKey": null }
如果字段名称或类型存在差异,或者需要在搜索索引中使用多个版本的源字段,请指定字段映射。
有关其他属性的详细信息,请参阅创建索引器。
创建索引器后,它会自动运行。 可以将“已禁用”设置为 true 以防止这种情况。 若要控制索引器执行,请按需运行索引器或按计划运行索引器。
检查索引器状态
若要监视索引器状态和执行历史记录,请发送获取索引器状态请求:
GET https://myservice.search.azure.cn/indexers/myindexer/status?api-version=2024-05-01-preview
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
]
}
执行历史记录包含最多 50 个最近完成的执行,它们按时间倒序排列,这样最新的执行最先显示。
为新文档和已更改的文档编制索引
索引器完全填充搜索索引后,建议运行后续的索引器,以便仅对数据库中的新文档和已更改的文档进行增量索引编制。
若要启用增量索引编制,请在数据源定义中设置“dataChangeDetectionPolicy”属性。 此属性告知索引器对数据使用哪种更改跟踪机制。
对于 Azure Cosmos DB 索引器,唯一支持的策略是使用 Azure Cosmos DB 提供的 _ts
(时间戳)属性的 HighWaterMarkChangeDetectionPolicy
。
以下示例演示具有更改检测策略的数据源定义:
"dataChangeDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
" highWaterMarkColumnName": "_ts"
},
为已删除的文档编制索引
从集合中删除行时,通常还需要从搜索索引中删除这些行。 数据删除检测策略旨在有效识别已删除的数据项。 目前,唯一支持的策略是 Soft Delete
策略(删除标有某种类型的标志),它在数据源定义中指定如下:
"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"
}
如果使用自定义查询,请确保查询投影由 softDeleteColumnName
引用的属性。
下面的示例创建具有软删除策略的数据源:
POST https://[service name].search.azure.cn/datasources?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [Search service admin key]
{
"name": ["my-cosmosdb-mongodb-ds]",
"type": "cosmosdb",
"credentials": {
"connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.cn;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDB"
},
"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"
}
}
后续步骤
现在可以控制如何运行索引器、监视状态或计划索引器执行。 以下文章适用于从 Azure Cosmos DB 拉取内容的索引器: