为 Azure 文件中的数据编制索引

项目
10/21/2024

重要

根据补充使用条款，Azure 文件存储索引器目前为公共预览版。使用预览版 REST API（2020-06-30-preview 或更高版本）创建索引器数据源。

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

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

系统必备

Azure 文件存储、事务优化层。
提供源内容的 SMB 文件共享。不支持 NFS 共享。
包含文本的文件。如果有二进制数据，则可以包括 AI 扩充以进行图像分析。
对 Azure 存储的读取权限。 “完全访问”连接字符串包括授予对内容的访问的密钥。
若要构建与本文所示调用类似的 REST 调用，请使用 REST 客户端。

支持的文档格式

Azure 文件存储索引器可从以下文档格式提取文本：

CSV（请参阅为 CSV Blob 编制索引）
EML
EPUB
GZ
HTML
JSON（请参阅为 JSON blob 编制索引）
KML（用于地理表示形式的 XML）
Microsoft Office 格式：DOCX/DOC/DOCM、XLSX/XLS/XLSM、PPTX/PPT/PPTM、MSG（Outlook 电子邮件）、XML（2003 和 2006 Word XML）
公开文档格式：ODT、ODS、ODP
PDF
纯文本文件（另请参阅为纯文本编制索引）
RTF
XML
ZIP

如何为 Azure 文件存储编制索引

默认情况下，大多数文件将作为索引中的单个搜索文档编制索引，包括包含结构化内容的文件（例如 JSON 或 CSV），它们作为单个文本区块编制索引。

复合或嵌入式文档（例如 ZIP 存档、嵌入了带附件 Outlook 电子邮件的 Word 文档或带附件的 .MSG 文件）也以单一文档的形式编制索引。例如，从 .MSG 文件的附件中提取的所有图像将在 normalized_images 字段中返回。如果有图像，请考虑添加 AI 扩充，以从该内容中获取更多搜索实用工具。

文档的文本内容将提取到名为 "content" 的字符串字段中。还可以提取标准和用户定义的元数据。

定义数据源

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

你可以为 "type" ："azurefile" 使用 2020-06-30-preview 或更高版本。建议使用最新的预览版 API。

使用“type”的预览 API 创建数据源来设置其定义："azurefile"。

POST /datasources?api-version=2024-05-01-preview
{
    "name" : "my-file-datasource",
    "type" : "azurefile",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-file-share", "query" : "<optional-directory-name>" }
}

将 "type" 设置为 "azurefile"（必需）。
将 "credentials" 设置为一个 Azure 存储连接字符串。下一部分介绍受支持的格式。
将 "container" 设置为根文件共享，并使用 "query" 指定任何子文件夹。

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

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

索引器可以使用以下连接连接到文件共享。

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

将搜索字段添加到索引

在搜索索引中，添加字段以接受 Azure 文件的内容和元数据。

创建或更新索引以定义将存储文件内容和元数据的搜索字段。

POST /indexes?api-version=2024-07-01
{
  "name" : "my-search-index",
  "fields": [
      { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
      { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
      { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
      { "name": "metadata_storage_path", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },
      { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
      { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true }        
  ]
}

创建文档键字段 ("key": true)。对于 Blob 内容，最佳候选项是元数据属性。元数据属性通常包括对文档键无效的字符，例如 / 和 -。索引器会自动将关键元数据属性编码，而无需进行配置或字段映射。
- metadata_storage_path（默认）对象或文件的完整路径
- metadata_storage_name 仅在名称唯一时可用
- 要添加到 Blob 中的自定义元数据属性。这种做法需要 Blob 上传过程将该元数据属性添加到所有 Blob。由于键是必需的属性，因此无法对任何缺少值的 blob 编制索引。如果使用自定义元数据属性作为键，请避免更改该属性。如果键属性发生更改，索引器将为同一 Blob 添加重复的文档。
添加 "content"字段，以通过 Blob 的 "content" 属性存储从每个文件中提取的文本。不需要使用此名称，但这样做则可以利用隐式字段映射。
为标准元数据属性添加字段。在文件索引中，标准元数据属性与 Blob 元数据属性相同。 Azure 文件存储索引器自动为这些属性创建内部字段映射，将包含连字符的属性名称转换为包含下划线的属性名称。你仍需添加要使用索引定义的字段，但是无需在数据源中创建字段映射。
- metadata_storage_name (Edm.String) - 文件名。例如，对于文件 /my-share/my-folder/subfolder/resume.pdf 而言，此字段的值是 resume.pdf。
- metadata_storage_path (Edm.String) - 文件的完整 URI，其中包括存储帐户。例如： https://myaccount.file.core.chinacloudapi.cn/my-share/my-folder/subfolder/resume.pdf
- metadata_storage_content_type Edm.String - 用于上传文件的代码指定的内容类型。例如，application/octet-stream。
- metadata_storage_last_modified (Edm.DateTimeOffset) - 文件上次修改的时间戳。 Azure AI 搜索使用此时间戳来识别已更改的文件，避免在初次编制索引之后再次为所有内容编制索引。
- metadata_storage_size (Edm.Int64) - 文件大小，以字节为单位。
- metadata_storage_content_md5 (Edm.String) - 文件内容的 MD5 哈希（如果有）。
- metadata_storage_sas_token (Edm.String) - 一个临时 SAS 令牌，可由自定义技能用来获取对文件的访问权限。此令牌可能会过期，因此不应存储起来供后续使用。

配置并运行 Azure 文件存储索引器

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

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

POST /indexers?api-version=2024-07-01
{
  "name" : "my-file-indexer",
  "dataSourceName" : "my-file-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
     "batchSize": null,
     "maxFailedItems": null,
     "maxFailedItemsPerBatch": null,
     "configuration": {
        "indexedFileNameExtensions" : ".pdf,.docx",
        "excludedFileNameExtensions" : ".png,.jpeg" 
    }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

在可选的 "configuration" 部分中，提供任何包括或排除条件。如果未指定任何条件，则检索文件共享中的所有文件。

如果同时存在 indexedFileNameExtensions 和 excludedFileNameExtensions 参数，Azure AI 搜索服务会先查找 indexedFileNameExtensions，再查找 excludedFileNameExtensions。如果两个列表中存在同一个文件扩展名，将从索引编制中排除该扩展名。
如果字段名称或类型存在差异，或者需要在搜索索引中使用多个版本的源字段，请指定字段映射。

在文件索引编制中，通常可以省略字段映射，因为索引器内置支持将 "content" 和元数据属性映射到索引中命名和类型类似的字段。对于元数据属性，索引器自动将搜索索引中的连字符 - 替换为下划线。
有关其他属性的详细信息，请参阅创建索引器。

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

检查索引器状态

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

GET https://myservice.search.azure.cn/indexers/myindexer/status?api-version=2024-07-01
  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 个最近完成的执行，它们按时间倒序排列，这样最新的执行最先显示。

后续步骤

现在可以运行索引器、监视状态或计划索引器执行。以下文章适用于从 Azure 存储拉取内容的索引器：

通过