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

mongoDB 索引器Azure Cosmos DB（预览版）从 mongoDB 的 Azure Cosmos DB 导入内容，并使它在 Azure AI 搜索中可搜索。

本文补充了 创建索引器 ，其中包含特定于 Cosmos DB 的信息。 它使用 REST API 来演示所有索引器通用的三部分工作流：创建数据源、创建索引、创建索引器。 提交创建索引器请求时，会发生数据提取。

由于术语可能令人困惑，因此值得注意的是，Azure Cosmos DB索引编制和Azure AI 搜索索引是不同的操作。 Azure AI 搜索中的索引会在搜索服务中创建并加载搜索索引。

先决条件

• 完成 索引器预览注册表单。 注册会自动获得批准。

• Azure Cosmos DB帐户、数据库、集合和文档。 对Azure AI 搜索和Azure Cosmos DB使用相同的区域来降低延迟并避免带宽费用。

• Azure Cosmos DB集合上的自动索引策略设置为 Consistent。 此设置是默认配置。 不建议使用延迟索引，可能会导致数据缺失。

• 读取权限。 “完全访问权限”连接字符串包含对内容授予访问权限的密钥，但如果使用的是 Azure 角色，请确保搜索服务托管标识具有“Cosmos DB 帐户读者角色”权限。

• 用于创建数据源、索引和索引器的 REST 客户端 。

限制

以下是此功能的限制：

• 用于指定数据集时不支持自定义查询。

• 列名 _ts 是保留字。 如果需要此字段，请考虑用于填充索引的替代解决方案。

• MongoDB 属性 $ref 是保留字。 如果需要在 MongoDB 集合中执行此操作，请考虑用于填充索引的替代解决方案。

作为此连接器的替代方法，如果你的方案具有上述任一要求，则可以使用 Push API/SDK或将 Azure 数据工厂与 Azure AI 搜索 index 用作接收器。

定义数据源

数据源定义指定要索引的数据、凭据以及用于识别数据变化的策略。 数据源定义为独立资源，以便多个索引器可以使用它。

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

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

   POST https://[service name].search.windows.net/datasources?api-version=2026-08-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.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb;"
     },
     "container": {
       "name": "[cosmos-db-collection]"
     },
     "dataChangeDetectionPolicy": {
       "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
       "highWaterMarkColumnName": "_ts"
     },
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
   }
   

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

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

4. 将“容器”设置为集合。 需要“name”属性，并指定要编制索引的数据库集合的 ID。 对于 Azure Cosmos DB for MongoDB，不支持“query”。

5. 如果数据易失，并且希望索引器在后续运行时只选取新的和更新的项目，请设置“dataChangeDetectionPolicy”。

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

支持的凭据和连接字符串

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

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

将搜索字段添加到索引

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

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

   POST https://[service name].search.windows.net/indexes?api-version=2026-08-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. 为更多可搜索内容创建其他字段。 有关详细信息 ，请参阅“创建索引 ”。

映射数据类型

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

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

1. 通过为其提供名称和引用数据源和目标索引来创建或更新索引器：

   POST https://[service name].search.windows.net/indexers?api-version=2026-08-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. 有关其他属性的详细信息，请参阅 “创建索引器 ”。

索引器在创建时自动运行。 可以通过将“disabled”设置为 true 来阻止此操作。 若要控制索引器执行， 请按需运行索引器 或 将其设置为定期运行。

检查索引器状态

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-08-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 索引器，唯一受支持的策略是使用 HighWaterMarkChangeDetectionPolicy 提供的 _ts（timestamp）属性。

以下示例显示了具有更改检测策略的 数据源定义 ：

"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.windows.net/datasources?api-version=2026-08-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.com;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数据库的索引器连接
• 为大型数据集编制索引
• Indexer 访问受 Azure 网络安全功能保护的内容