为 Azure 表存储中的数据编制索引

2025-10-24

本文将介绍如何配置索引器，该索引器从 Azure 表存储导入内容，并使内容在 Azure AI 搜索中可供搜索。索引器的输入是单个表中的实体。输出是一个搜索索引，其中包含可搜索的内容和存储在各个字段中的元数据。

本文对创建索引器进行了补充，提供了特定于从 Azure 表存储编制索引的信息。它使用 Azure 门户和 REST API 演示所有索引器通用的工作流，该工作流包含三个部分：创建数据源、创建索引、创建索引器。提交“创建索引器”请求时，将提取数据。

先决条件

Azure 表存储
包含文本的表。如果你有二进制数据，请考虑使用 AI 扩充进行图像分析。
对 Azure 存储的读取权限。 “完全访问权限”连接字符串包含授予对内容的访问权限的密钥，但如果使用的是 Azure 角色，请确保搜索服务托管标识具有“存储表数据读取者”权限。

若要完成本文中的示例，你需要 Azure 门户或一个 REST 客户端。如果使用 Azure 门户，请确保启用对所有公用网络的访问权限。创建 Azure 表索引器的其他方法包括 Azure SDK。

使用示例数据进行尝试

按这些说明在 Azure 存储中创建表进行测试。

登录 Azure 门户，导航到你的存储帐户，然后创建名为 hotels 的表。
安装 Azure 存储资源管理器。
从 GitHub 中下载 HotelsData_toAzureSearch.csv。此文件是内置 hotels 示例数据集的子集。它省略了房间集合、已翻译的说明和地理坐标。
在 Azure 存储资源管理器中，登录 Azure，选择你的订阅，然后选择存储帐户。
打开“表”并选择 hotels。
在命令栏上选择“导入”，然后选择 HotelsData_toAzureSearch.csv 文件。
接受默认值。选择“导入”以加载数据。

表中应有 50 条酒店记录，其中包含自动生成的 partitionKey、rowKey 和时间戳。现在，便可使用此内容在 Azure 门户、REST 客户端或 Azure SDK 中编制索引。

“说明”字段提供了最详细的内容。你应该针对该字段进行全文搜索和可选矢量查询。

使用 Azure 门户

可以使用 导入数据 向导或 导入数据（新） 向导从 SQL 数据库表或视图中自动编制索引。这两个向导的数据源配置类似。

启动向导。
在“连接到数据”上，选择或验证数据源类型是否为 Azure 表存储，或者数据选择字段是否提示输入表。

数据源名称是指 Azure AI 搜索中的数据源连接对象。如果你使用矢量向导，则系统会使用向导工作流结束时指定的自定义前缀自动生成数据源名称。
指定存储帐户和表单名称。查询为可选。如果你具有要导入的特定列会很有用。
指定身份验证方法，该方法可以是托管标识，也可以是内置 API 密钥。如果未指定托管标识连接，Azure 门户会使用该密钥。

如果将 Azure AI 搜索配置为使用托管标识，并在 Azure 存储上创建角色分配，以向标识授“读取器和数据访问”权限，则索引器可以使用 Microsoft Entra ID 和角色连接到表存储。
对于 导入数据（新建） 向导，可以指定用于删除检测的选项。

删除检测要求表中有一个预先存在的字段，该字段可用作软删除标志。它应该是一个布尔字段（可以将其命名为 IsDeleted）。将 true 指定为软删除值。在搜索索引中，添加一个名为“IsDeleted”且已设置为可检索和可筛选的相应搜索字段。
继续执行剩余步骤以完成该向导：
- 导入数据 向导
- 导入数据（新建） 向导

使用 REST API

本部分演示可创建数据源、索引和索引器的 REST API 调用。

定义数据源

数据源定义指定要编制索引的源数据、凭据和更改检测策略。数据源是一个独立的资源，可由多个索引器使用。

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

 POST https://[service name].search.azure.cn/datasources?api-version=2025-09-01 
 {
     "name": "my-table-storage-ds",
     "description": null,
     "type": "azuretable",
     "subtype": null,
     "credentials": {
        "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>"
     },
     "container": {
        "name": "my-table-in-azure-storage",
        "query": ""
     },
     "dataChangeDetectionPolicy": null,
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null,
     "identity": null
 }

将 "type" 设置为 "azuretable"（必需）。
将 "credentials" 设置为一个 Azure 存储连接字符串。下一部分介绍受支持的格式。
将 "container" 设置为表的名称。
（可选）将 "query" 设置为 PartitionKey 上的筛选器。设置此属性是可提高性能的最佳做法。如果“query”为 null，则索引器将执行完整的表扫描，如果表很大，这可能会导致性能不佳。

如果希望索引器在源文档被标记为待删除时删除搜索文档，则数据源定义还可以包含软删除策略。

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

索引器可以使用以下连接连接到表。

完全访问存储帐户连接字符串
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
可以通过在左窗格中选择 “访问密钥 ”，从 Azure 门户中的“存储帐户”页获取连接字符串。请确保选择完整的连接字符串，而不只是一个密钥。

托管标识连接字符串
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
此连接字符串不需要帐户密钥，但先前必须已将搜索服务配置为使用托管标识进行连接。

存储帐户共享访问签名** (SAS) 连接字符串
`{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.chinacloudapi.cn/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }`
SAS 应具有表和实体的列表和读取权限。

容器共享访问签名
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.chinacloudapi.cn/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
SAS 应具有容器的列表和读取权限。有关详细信息，请参阅使用共享访问签名。

注释

如果使用 SAS 凭据，则需使用续订的签名定期更新数据源凭据，以防止其过期。如果 SAS 凭据过期，索引器会失败并出现类似于“连接字符串中提供的凭据无效或已过期”的错误消息。

分区以提高性能

默认情况下，Azure AI 搜索使用以下内部查询筛选器来跟踪自上次运行以来已更新哪些源实体：Timestamp >= HighWaterMarkValue。由于 Azure 表在 Timestamp 字段上没有辅助索引，因此该类型的查询需要执行全表扫描，导致大型表查询速度慢。

为避免完全扫描，可以使用表分区来缩小每个索引器作业的范围。

如果数据可以自然地分区到多个分区范围中，请为每个分区范围创建数据源和相应的索引器。现在每个索引器仅能处理一个特定分区范围，使得查询性能更佳。如果需编制索引的数据具有较少的固定分区，查询性能会更好：每个索引器仅执行一次分区扫描。

例如，若要创建一个数据源来处理含有 000 到 100 键的分区范围，请使用类似于以下内容的查询："container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }
如果数据按时间分区（例如，如果每天或每周创建一个新分区），请考虑以下方法：
- 在数据源定义中，指定类似于以下示例的查询：(PartitionKey ge <TimeStamp>) and (other filters)。
- 使用获取索引器状态 API监视器索引器进度，并基于最新的成功的高使用标记值定期更新查询的 <TimeStamp> 条件。
- 借助此方法，如果需要触发完整的索引重编制，除了重置索引器外还需要重置数据源查询。

将搜索字段添加到索引

在搜索索引中，添加字段以接受表实体的内容和元数据。

创建或更新索引以定义将要存储实体中内容的搜索字段：

POST https://[service name].search.azure.cn/indexes?api-version=2025-09-01 
{
  "name" : "my-search-index",
  "fields": [
    { "name": "Key", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
  ]
}

创建文档键字段 ("key": true)，但允许索引器自动填充该字段。表索引器使用表中的连接分区键和行键填充键字段。例如，如果一行的 PartitionKey 为 1，RowKey 为 1_123，则键值为 11_123。如果分区键为 null，则仅使用行键。

如果使用导入数据向导创建索引，则 Azure 门户将为搜索索引推理一个“Key”字段，并使用隐式字段映射来连接源字段和目标字段。你不需要自行添加该字段，也不需要设置字段映射。

如果你正在使用 REST API 且不想使用隐式字段映射，请在搜索索引定义中创建并命名文档键字段“Key”，如上一步骤所示 ({ "name": "Key", "type": "Edm.String", "key": true, "searchable": false })。索引器会自动填充 Key 字段，而不需要字段映射。

如果你不想在搜索索引中添加名为“Key”的字段，请在索引器定义中添加包含所需字段名称的显式字段映射，并将源字段设置为“Key”：
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Key",
     "targetFieldName" : "MyDocumentKeyFieldName"
   }
]
```
现在，在索引中添加所需的任何其他实体字段。例如，如果实体如以下示例所示，则搜索索引应包含 HotelName、Description 和 Category 字段以接收这些值。

使用相同的名称和兼容的数据类型可最大程度地减少对字段映射的需求。当名称和类型相同时，索引器可以自动确定数据路径。

配置和运行表索引器

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

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

POST https://[service name].search.azure.cn/indexers?api-version=2025-09-01
{
    "name" : "my-table-indexer",
    "dataSourceName" : "my-table-storage-ds",
    "targetIndexName" : "my-search-index",
    "disabled": null,
    "schedule": null,
    "parameters" : {
        "batchSize" : null,
        "maxFailedItems" : null,
        "maxFailedItemsPerBatch" : null,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

如果字段名称或类型存在差异，或者需要在搜索索引中使用多个版本的源字段，请指定字段映射。 Target 字段是搜索索引中字段的名称。
```
 "fieldMappings" : [
   {
     "sourceFieldName" : "Description",
     "targetFieldName" : "HotelDescription"
   }
]
```
有关其他属性的详细信息，请参阅创建索引器。

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

检查索引器状态

若要监视索引器状态和执行历史记录，请在 Azure 门户中检查索引器执行历史记录，或发送“获取索引器状态”REST API 请求

Portal
REST

在搜索服务页面上，打开“搜索管理”>“索引器”。
选择一个索引器来访问配置和执行历史记录。
选择特定的索引器作业来查看详细信息、警告和错误。

GET https://myservice.search.azure.cn/indexers/myindexer/status?api-version=2025-09-01
  Content-Type: application/json  
  api-key: [admin key]

响应包括状态和已处理的项数。它应如下例所示：

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2023-02-21T00:23:24.957Z",
            "endTime":"2023-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2023-02-21T00:23:24.957Z",
                "endTime":"2023-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

执行历史记录包含最多 50 个最近完成的执行，它们按时间倒序排列，这样最新的执行最先显示。

后续步骤

详细了解如何运行索引器、监视状态或计划索引器执行。以下文章适用于从 Azure 存储拉取内容的索引器：

Compartilhar via