为 Azure AI 搜索 中的查询编制 Azure Cosmos DB for MongoDB 中的数据索引（预览版）

本文介绍如何配置从 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 数据工厂 与 Azure AI 搜索索引 视为接收器。

定义数据源

数据源定义指定要编制索引的数据、凭据和用于标识数据更改的策略。 数据源定义为独立的资源，以便它可以被多个索引器使用。

对于此调用，请指定 预览版 REST API 版本。 可以使用 2020-06-30-preview 或更高版本创建通过 MongoDB API 连接的数据源。 建议使用最新的预览版 REST API。

1. 创建或更新数据源以设置其定义：

   POST https://[service name].search.azure.cn/datasources?api-version=2026-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
   }
   

2. 将 "type" 设置为 "cosmosdb"（必需）。

3. 将“credentials”设置为连接字符串。 下一部分介绍受支持的格式。

4. 将“container”设置为该集合。 “名称”属性是必填的，它指定要编制索引的数据库集合的 ID。 对于 Azure Cosmos DB for MongoDB，不支持“查询”。

5. 如果数据经常变动，且你希望索引器在后续运行时只获取新项和更新的项，则设置“dataChangeDetectionPolicy”。

6. 如果要在删除源项时从搜索索引中删除搜索文档，则设置“dataDeletionDetectionPolicy”。

受支持的凭据和连接字符串

索引器可以使用以下连接连接到集合。 对于面向 MongoDB API 的连接，请确保在连接字符串中包含“ApiKind”。

避免在终结点 URL 中包含端口号。 如果包含端口号，连接将失败。

将搜索字段添加到索引

在搜索索引中，添加字段以接受源 JSON 文档或自定义查询投影的输出。 确保搜索索引架构与源数据兼容。 对于 Azure Cosmos DB 中的内容，搜索索引架构应对应于数据源中的 Azure Cosmos DB 项。

1. 创建或更新索引 以定义将存储数据的搜索字段：

   POST https://[service name].search.azure.cn/indexes?api-version=2026-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
       }]
   }
   

2. 创建一个文档键字段（"key": true）。 对于基于 MongoDB 集合的搜索索引，文档键可以是“doc_id”、“rid”或其他包含唯一值的字符串字段。 只要两端的字段名称和数据类型相同，就不需要字段映射。

   • “doc_id”表示对象标识符的“_id”。 如果在索引中指定了“doc_id”字段，索引器将使用对象标识符的值填充该字段。

   • “rid”是 Azure Cosmos DB 中的系统属性。 如果在索引中指定了“rid”字段，索引器将使用“rid”属性的 base64 编码值填充该字段。

   • 对于任何其他字段，搜索字段的名称应与集合中定义的名称相同。

3. 为更多可搜索内容创建其他字段。 有关详细信息，请参阅创建索引。

映射数据类型

配置并运行 Azure Cosmos DB for MongoDB 索引器

创建索引和数据源后，便可以准备创建索引器。 索引器配置指定控制运行时行为的输入、参数和属性。

1. 通过为索引器命名并引用数据源和目标索引来创建或更新索引器：

   POST https://[service name].search.azure.cn/indexers?api-version=2026-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
   }
   

2. 如果字段名称或类型存在差异，或者需要在搜索索引中使用多个版本的源字段，请指定字段映射。

3. 有关其他属性的详细信息，请参阅创建索引器。

创建索引器后，它会自动运行。 可以将“已禁用”设置为 true 以防止这种情况。 若要控制索引器执行，请按需运行索引器或按计划运行索引器。

检查索引器状态

若要监视索引器状态和执行历史记录，请发送获取索引器状态请求：

GET https://myservice.search.azure.cn/indexers/myindexer/status?api-version=2026-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=2026-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 拉取内容的索引器：

• 使用托管标识设置索引器与 Azure Cosmos DB 数据库之间的连接
• 为大型数据集编制索引
• 索引器访问受 Azure 网络安全功能保护的内容