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

项目
03/25/2024

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

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

必备条件

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

定义数据源

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

 POST https://[service name].search.azure.cn/datasources?api-version=2023-11-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=2023-11-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，则仅使用行键。

如果使用导入数据向导创建索引，则门户将为搜索索引推理一个“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=2023-11-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,
        "base64EncodeKeys" : null,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

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

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

检查索引器状态

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

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