你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

注释

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

重要

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

重要

这些特性和功能支持与其他Microsoft 服务和第三方服务的连接。使用这些服务受其各自的条款的约束，可能会导致数据处理或存储超出Azure符合性边界，以及流入Azure符合性边界的数据。

您有责任管理您的数据是否会流出您组织的合规和地理边界之外及其任何相关影响，并确保已配置适当的权限、边界和审批。

你负责仔细查看和测试在特定用例上下文中生成的应用程序，并做出所有适当的决策和自定义。这包括实施自己的负责任的 AI 缓解措施，例如元系统、内容筛选器或其他安全系统，并确保应用程序满足适当的质量、可靠性、安全性和可信度标准。有关详细信息，请参阅 Azure AI 搜索透明度说明。

Apache Gremlin 索引器Azure Cosmos DB（预览版）从 apache Gremlin 的 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 客户端。

定义数据源

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

对于此调用，请指定预览版 REST API 版本，以创建通过 apache Gremlin Azure Cosmos DB连接的数据源。可以使用 2021-04-01-preview 或更高版本。建议使用最新的预览版 REST API。

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

 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-gremlin-ds]",
   "type": "cosmosdb",
   "credentials": {
     "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin;"
   },
   "container": {
     "name": "[cosmos-db-collection]",
     "query": "g.V()"
   },
   "dataChangeDetectionPolicy": {
     "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
     "highWaterMarkColumnName": "_ts"
   },
   "dataDeletionDetectionPolicy": null,
   "encryptionKey": null,
   "identity": null
 }

将“type”设置为 "cosmosdb" （必需）。
将“凭据”设置为连接字符串。下一部分介绍支持的格式。
将“容器”设置为集合。 “name”属性是必需的，它指定图形的 ID。

“query”属性是可选的。默认情况下，apache Gremlin Azure Cosmos DB的Azure AI 搜索索引器会使图形中的每个顶点都成为索引中的文档。边缘将被忽略。查询默认值为 g.V(). 或者，你可以将查询设置为边缘编制索引。若要为边缘编制索引，请将查询设置为 g.E()。
如果数据易失，并且希望索引器在后续运行时只选取新的和更新的项目，请设置“dataChangeDetectionPolicy”。默认情况下，使用 _ts 作为高水位标记列来启用增量进度。
如果要在删除源项时从搜索索引中删除搜索文档，请设置“dataDeletionDetectionPolicy”。

支持的凭据和连接字符串

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

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

完全访问连接字符串
`{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=Gremlin" }`
可以通过在左窗格中选择 Keys，并从 Azure 门户中的 Azure 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.windows.net/indexes?api-version=2026-08-01-preview
 Content-Type: application/json
 api-key: [Search service admin key]
 {
    "name": "mysearchindex",
    "fields": [
     {
         "name": "rid",
         "type": "Edm.String",
         "facetable": false,
         "filterable": false,
         "key": true,
         "retrievable": true,
         "searchable": true,
         "sortable": false,
         "analyzer": "standard.lucene",
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "synonymMaps": [],
         "fields": []
     }, {
         "name": "label",
         "type": "Edm.String",
         "searchable": true,
         "filterable": false,
         "retrievable": true,
         "sortable": false,
         "facetable": false,
         "key": false,
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "analyzer": "standard.lucene",
         "synonymMaps": []
    }]
  }

创建文档键字段（“key”： true）。对于分区集合，默认文档键是 Azure Cosmos DB _rid 属性，该属性Azure AI 搜索自动重命名为 rid，因为字段名称不能以下划线字符开头。此外，Azure Cosmos DB _rid 值中包含的字符在 Azure AI 搜索键中无效。因此，这些 _rid 值是 Base64 编码的。
为更多可搜索内容创建其他字段。有关详细信息，请参阅“创建索引 ”。

映射数据类型

JSON 数据类型	Azure AI 搜索字段类型
布尔	Edm.Boolean、Edm.String
看起来像整数的数字	Edm.Int32、Edm.Int64、Edm.String
看起来像浮点的数字	Edm.Double、Edm.String
字符串	Edm.String
基元类型的数组，例如 [“a”、“b”、“c”]	Collection（Edm.String）
类似于日期的字符串	Edm.DateTimeOffset、Edm.String
GeoJSON 对象，如 { “type”： “Point”， “coordinates”： [long， lat] }	Edm.GeographyPoint
其他 JSON 对象	N/A

配置并运行Azure Cosmos DB索引器

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

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

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-gremlin-ds]",
    "targetIndexName" : "[my-search-index]",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": false,
        "configuration": {}
        },
    "fieldMappings": [],
    "encryptionKey": null
}

如果字段名称或类型存在差异，或者搜索索引中需要多个版本的源字段，请指定字段映射。
有关其他属性的详细信息，请参阅 “创建索引器 ”。

索引器在创建时自动运行。可以通过将“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"
}

以下示例使用软删除策略创建数据源：

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-gremlin-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin"
    },
    "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"
    }
}

即使启用删除检测策略，也不支持从索引中删除复杂（Edm.ComplexType）字段。此策略要求 Gremlin 数据库中的“活动”列的类型为整数、字符串或布尔值。

将图形数据映射到搜索索引中的字段

Apache Gremlin 索引器的Azure Cosmos DB会自动映射几个图形数据片段：

如果存在，索引器会将 _rid 映射到索引中的 rid 字段，并对其进行 Base64 编码。
索引器会将 _id 映射到索引中的 id 字段（如果该字段存在）。
使用 Azure Cosmos DB for Apache Gremlin 查询 Azure Cosmos DB 数据库时，你可能会注意到，每个属性的 JSON 输出都具有 id 和 value。索引器会自动将属性 value 映射到搜索索引中的字段，该字段与该属性存在时的名称相同。在以下示例中，450 映射到 pages 搜索索引中的字段。

    {
        "id": "Cookbook",
        "label": "book",
        "type": "vertex",
        "properties": {
          "pages": [
            {
              "id": "48cf6285-a145-42c8-a0aa-d39079277b71",
              "value": "450"
            }
          ]
        }
    }

你可能会发现需要使用输出字段映射将查询输出映射到索引中的字段。你可能希望使用输出字段映射，而不是字段映射，因为自定义查询可能具有复杂的数据。

例如，假设查询生成以下输出：

    [
      {
        "vertex": {
          "id": "Cookbook",
          "label": "book",
          "type": "vertex",
          "properties": {
            "pages": [
              {
                "id": "48cf6085-a211-42d8-a8ea-d38642987a71",
                "value": "450"
              }
            ],
          }
        },
        "written_by": [
          {
            "yearStarted": "2017"
          }
        ]
      }
    ]

如果要将上述 pages JSON 中的值totalpages映射到索引中的字段，可以将以下输出字段映射添加到索引器定义：

    ... // rest of indexer definition 
    "outputFieldMappings": [
        {
          "sourceFieldName": "/document/vertex/pages",
          "targetFieldName": "totalpages"
        }
    ]

请注意，输出字段映射以/document开头，并且不包括对JSON中属性键的引用。这是因为索引器在引入图形数据时将每个文档放在节点下/document，索引器还自动允许通过简单的引用pages来引用值pages，而无需引用数组pages中的第一个对象。

后续步骤

若要了解有关 Azure Cosmos DB for Apache Gremlin 的详细信息，请参阅 Azure Cosmos DB 简介：Azure Cosmos DB for Apache Gremlin。
有关 Azure AI 搜索方案和定价的详细信息，请参阅 azure.microsoft.com 上的搜索服务页。
若要了解索引器的网络配置，请参阅 Indexer 访问受Azure网络安全功能保护的内容。

反馈

此页面是否有帮助？

Last updated on 2026-09-17