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

OneLake 文件和快捷方式的索引数据

项目
11/19/2024

在本文中，了解如何配置 OneLake 文件索引器，以便从 OneLake 顶部的湖屋中提取可搜索数据和元数据数据。

若要配置和运行索引器，可以使用：

2024-05-01-preview REST API 或更新的预览版 REST API。
一个提供该功能的 Azure SDK beta 版包。
Azure 门户中的导入数据向导。
Azure 门户中的导入和矢量化数据向导。

本文使用 REST API 来说明每个步骤。

先决条件

一个 Fabric 工作区。按照本教程创建 Fabric 工作区。
Fabric 工作区中的湖屋。按照本教程创建湖屋。
文本数据。如有二进制数据，则可以使用 AI 扩充图像分析来提取文本或生成图像描述。文件内容不得超出搜索服务层的索引器限制。
湖屋文件位置中的内容。可以通过以下方式添加数据：
- 直接上传到湖屋
- 使用 Microsoft Fabric 中的数据管道
- 添加快捷方式，它们来自外部数据源（如 Amazon S3 或 Google Cloud Storage）。
为系统托管标识或用户分配的托管标识配置的 AI 搜索服务。 AI 搜索服务必须与 Microsoft Fabric 工作区驻留在同一租户中。
湖屋所在的 Microsoft Fabric 工作区中的参与者角色分配。本文的“授予权限”部分概述了这些步骤。
REST 客户端，用于制定与本文中所示类似的 REST 调用。

受支持的任务

可以将此索引器用于以下任务：

数据索引和增量索引：索引器可以从湖屋内的数据路径中索引文件和相关元数据。它透过内置的更改检测来检测新的和更新的文件及元数据。可以按计划或按需配置数据刷新。
删除检测：索引器可以通过大多数文件和快捷方式的自定义元数据检测删除。这需要向文件添加元数据，以表示它们已“软删除”，从而能够从搜索索引中删除。目前，无法在 Google Cloud Storage 或 Amazon S3 快捷方式文件中检测到删除，因为这些数据源不支持自定义元数据。
通过技能组应用的 AI：OneLake 文件索引器完全支持技能组。这包括集成向量化等关键功能，用于添加数据分块和嵌入步骤。
解析模式：如果想将 JSON 数组或行分析为单独的搜索文档，则索引器支持 JSON 分析模式。它还支持 Markdown 分析模式。
与其他功能的兼容性：OneLake 索引器旨在与其他索引器功能无缝配合，如调试会话、用于增量扩充的索引器缓存和知识存储。

支持的文档格式

OneLake 文件索引器可以从以下文档格式中提取文本：

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

支持的快捷方式

OneLake 文件索引器支持以下 OneLake 快捷方式：

此预览中的限制

目前不支持 Parquet（包括 delta parquet）文件类型。
Amazon S3 和 Google Cloud Storage 快捷方式不支持文件删除。
此索引器不支持 OneLake 工作区表位置内容。
此索引器不支持 SQL 查询，但数据源配置中使用的查询仅用于添加要访问的文件夹或快捷方式。
不支持从 OneLake 中的“我的工作区”工作区引入文件，因为这是每个用户的个人存储库。

准备用于索引的数据

确定要索引哪些 blob在建立索引之前，请查看源数据，以确定是否应提前进行任何更改。索引器一次可以为一个容器中的内容编制索引。默认情况下，将处理容器中的所有文件。有多个选项来进行更有选择性的处理：

将文件放在虚拟文件夹中。索引器数据源定义包括“查询”参数，它可以是湖屋子文件夹或快捷方式。如果指定了此值，则仅会未湖屋中子文件夹或快捷方式中的那些文件编制索引。
按文件类型包括或排除文件。支持的文档格式列表可以帮助确定要排除的文件。例如，你可能希望排除不提供可搜索文本的图像或音频文件。此功能通过索引器中的配置设置进行控制。
包括或排除任意文件。如果出于任何原因想要跳过特定文件，可以将元数据属性和值添加到 OneLake 湖屋中的文件中。当索引器遇到此属性时，它会跳过索引运行中的文件或其内容。

索引器配置步骤包括文件包含和排除。如果不设置条件，索引器会将不符合条件的文件报告为错误，然后继续。如果出现足够多的错误，处理可能会停止。可在索引器配置设置中指定错误容错。

索引器通常为每个文件创建搜索文档，其中文本内容和元数据会捕获为索引中的可搜索字段。如果文件是完整的文件，则可以将它们分析为多个搜索文档。例如，可以解析 CSV 文件中的行，以便为每行创建一个搜索文档。如果需要将单一文档分块到较小的段落中以矢量化数据，请考虑使用集成矢量化。

为文件元数据编制索引

还可以为文件元数据编制索引，如果你认为任何标准或自定义元数据属性在筛选器和查询中有用，则其会很实用。

可以逐字提取任何由用户指定的元数据属性。若要接收这些值，必须在 Edm.String 类型的搜索索引中定义字段，其名称与 blob 的元数据密钥名称相同。例如，如果 blob 有值为 High 的元数据密钥 Priority，则应在搜索索引中定义一个名为 Priority 的字段，该字段将用值 High 填充。

可以将标准文件元数据属性提取到下列名称和类型类似的字段中。 OneLake 文件索引器自动为这些元数据属性创建内部字段映射，将原始的连字符名称 ("metadata-storage-name") 转换为带下划线的等效名称 ("metadata_storage_name")。

仍需要将带下划线的字段添加到索引定义中，但可以省略索引器字段映射，因为索引器会自动进行关联。

metadata_storage_name (Edm.String) - 文件名。例如，对于文件 /mydatalake/my-folder/subfolder/resume.pdf 而言，此字段的值是 resume.pdf。
metadata_storage_path () - blob 的完整 URI，其中包括存储帐户。例如： https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf
metadata_storage_content_type - 用于上传 Blob 的代码指定的内容类型。例如，application/octet-stream。
metadata_storage_last_modified () - blob 的上次修改的时间戳。 Azure AI 搜索使用此时间戳来识别已更改的 blob，避免在初次编制索引之后再次为所有内容编制索引。
metadata_storage_size () - blob 大小，以字节为单位。
metadata_storage_content_md5 () - blob 内容的 MD5 哈希（如果有）。

最后，正在为其编制索引的文件文档格式的所有特定元数据属性也都可以在索引架构中表示。有关特定于内容的元数据的详细信息，请参阅内容元数据属性。

务必注意，无需在搜索索引中为上述所有属性定义字段 - 只需捕获应用程序所需的属性。

授予权限

OneLake 索引器使用令牌身份验证和基于角色的访问来连接 OneLake。在 OneLake 中分配权限。对支持快捷方式的物理数据存储没有权限要求。例如，如果从 AWS 进行索引，则不需要在 AWS 中授予搜索服务权限。

搜索服务标识的最低角色分配为“参与者”。

为 AI 搜索服务配置系统或用户托管标识。

下方屏幕截图显示了名为“onelake-demo”的搜索服务的系统托管标识。

此屏幕截图显示了同一搜索服务的用户托管标识。
向 Fabric 工作区授予搜索服务访问权限。搜索服务代表索引器进行连接。

如果使用系统分配的托管标识，请搜索 AI 搜索服务的名称。对于用户分配的托管标识，请搜索标识资源的名称。

下面的屏幕截图显示了使用系统托管标识“参与者”角色分配。

此屏幕截图显示了使用系统托管标识的“参与者”角色分配：

定义数据源

数据源定义为独立的资源，以便它可以被多个索引器使用。必须使用 2024-05-01-preview REST API 来创建数据源。

使用创建或更新数据源 REST API 来设置其定义。这些是定义中最重要的步骤。
将 "type" 设置为 "onelake"（必需）。
获取 Microsoft Fabric 工作区 GUID 和湖屋 GUID：
- 转到要从其 URL 导入数据的湖屋。它看起来应该类似于这个例子：“https://msit.powerbi.com/groups/00000000-0000-0000-0000-000000000000/lakehouses/11111111-1111-1111-1111-111111111111?experience=power-bi"；。复制数据源定义中使用的以下值：
- 复制工作区 GUID，我们称之为 {FabricWorkspaceGuid}，它列在 URL 中的“groups”后面。在本示例中，它将为 00000000-0000-0000-0000-000000000000。
- 复制我们将称之为 {lakehouseGuid} 的湖屋 GUID，它在 URL 中的“lakehouses”后面列出。在本示例中，它将为 11111111-1111-1111-1111-111111111111。
将 "credentials" 设置为 Microsoft Fabric 工作区 GUID，方法是将 {FabricWorkspaceGuid} 替换为上一步中复制的值。这是 OneLake，可以使用稍后将在本指南中设置的托管标识进行访问。
```
"credentials": {  
"connectionString": "ResourceId={FabricWorkspaceGuid}"  
}
```
将 "container.name" 设置为湖屋 GUID，将 {lakehouseGuid} 替换为上一步中复制的值。使用 "query" 可以选择指定湖屋子文件夹或快捷方式。
```
  "container": {  
    "name": "{lakehouseGuid}",  
    "query": "{optionalLakehouseFolderOrShortcut}"  
  }
```

使用用户分配的托管标识设置身份验证方法，或者跳到系统托管标识的下一步。

{    
  "name": "{dataSourceName}",  
  "description": "description",  
  "type": "onelake",  
  "credentials": {  
    "connectionString": "ResourceId={FabricWorkspaceGuid}"  
  },  
  "container": {  
    "name": "{lakehouseGuid}",  
    "query": "{optionalLakehouseFolderOrShortcut}"  
  },  
  "identity": {  
    "@odata.type": "Microsoft.Azure.Search.DataUserAssignedIdentity",  
    "userAssignedIdentity": "{userAssignedManagedIdentity}"  
  }  
}

userAssignedIdentity 值可以通过访问 {userAssignedManagedIdentity} 资源在“属性”下找到，它名为 Id。

示例：

{    
  "name": "mydatasource",  
  "description": "description",  
  "type": "onelake",  
  "credentials": {  
    "connectionString": "ResourceId=a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"  
  },  
  "container": {  
    "name": "11111111-1111-1111-1111-111111111111",  
    "query": "folder_name"  
  },  
  "identity": {  
    "@odata.type": "Microsoft.Azure.Search.DataUserAssignedIdentity",  
    "userAssignedIdentity": "/subscriptions/333333-3333-3333-3333-33333333/resourcegroups/myresourcegroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/demo-mi"  
  }  
}

或者，使用系统分配的托管标识。如果使用系统分配的托管标识，则从定义中删除“标识”。

{    
  "name": "{dataSourceName}",  
  "description": "description",  
  "type": "onelake",  
  "credentials": {  
    "connectionString": "ResourceId={FabricWorkspaceGuid}"  
  },  
  "container": {  
    "name": "{lakehouseGuid}",  
    "query": "{optionalLakehouseFolderOrShortcut}"  
  }  
}

示例：

{    
  "name": "mydatasource",  
  "description": "description",  
  "type": "onelake",  
  "credentials": {  
    "connectionString": "ResourceId=a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"  
  },  
  "container": {  
    "name": "11111111-1111-1111-1111-111111111111",  
    "query": "folder_name"  
  }
}

通过自定义元数据检测删除

如果希望索引器在源文档标记为删除时删除搜索文档，OneLake 文件索引器数据源定义可以包括软删除策略。

要启用自动文件删除，请使用自定义元数据指示是否应从索引中移除搜索文档。

工作流需要三个单独操作：

“软删除”OneLake 中的文件
索引器删除索引中的搜索文档
“硬删除”OneLake 中的文件

“软删除”告知索引器要执行的事项（删除搜索文档）。如果首先删除 OneLake 中的物理文件，索引器将无法读取任何内容，并且索引中相应的搜索文档将成为孤立文档。

OneLake 和 Azure AI 搜索都需要遵循一些步骤，但没有其他功能依赖项。

在湖屋文件中，将自定义元数据键值对添加到文件中，以指示该文件标记为删除。例如，可以将属性命名为“IsDeleted”，并将其设置为 false。如果要删除该文件，请将其更改为 true。

在 Azure AI 搜索中，编辑数据源定义以包含“dataDeletionDetectionPolicy”属性。例如，如果某个文件的元数据属性“IsDeleted”的值为 true，则以下策略会考虑删除文件：

PUT https://[service name].search.windows.net/datasources/file-datasource?api-version=2024-05-01-preview
{
    "name" : "onelake-datasource",
    "type" : "onelake",
     "credentials": {  
        "connectionString": "ResourceId={FabricWorkspaceGuid}"  
    },  
    "container": {  
        "name": "{lakehouseGuid}",  
        "query": "{optionalLakehouseFolderOrShortcut}"  
    },  
    "dataDeletionDetectionPolicy" : {
        "@odata.type" :"#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName" : "IsDeleted",
        "softDeleteMarkerValue" : "true"
    }
}

在索引器运行并从搜索索引中删除文档后，可以删除数据湖中的物理文件。

一些要点包括：

安排索引器运行有助于自动化此进程。建议所有增量索引方案都具有日程安排。
如果在第一次运行索引器时没有设置删除检测策略，则必须重置索引器，以便它读取更新的配置。
回想一下，由于自定义元数据的依赖项，Amazon S3 和 Google Cloud Storage 快捷方式不支持删除检测。

将搜索字段添加到索引

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

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

{
    "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_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true }     
    ]
}

创建文档键字段 ("key": true)。对于文件内容，最佳候选项是元数据属性。
- metadata_storage_path（默认）对象或文件的完整路径。键字段（本例中为“ID”）由 metadata_storage_path 中的值填充，因为这是默认值。
- metadata_storage_name 仅在名称唯一时可用。如果希望此字段作为键，请将 "key": true 移动到此字段定义。
- 添加到文件中的自定义元数据属性。此选项要求文件上传进程将该元数据属性添加到所有 Blob 中。由于键是必需属性，因此无法对任何缺少值的文件编制索引。如果使用自定义元数据属性作为键，请避免更改该属性。如果密钥属性发生更改，索引器会为同一文件添加重复文档。
元数据属性通常包括对文档键无效的字符，例如 / 和 -。因为索引器具有“base64EncodeKeys”属性（默认为 true），所以它会自动对元数据属性进行编码，无需进行配置或字段映射。
添加“内容”字段，通过文件的“内容”属性存储从每个文件提取的文本。不需要使用此名称，但这样做则可以利用隐式字段映射。
为标准元数据属性添加字段。索引器可以读取自定义元数据属性、标准元数据属性和内容特定的元数据属性。

配置并运行 OneLake 文件索引器

创建索引和数据源后，就已准备好创建索引器。索引器配置指定控制运行时行为的输入、参数和属性。还可指定要为 blob 的哪些部分编制索引。

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

{
  "name" : "my-onelake-indexer",
  "dataSourceName" : "my-onelake-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "base64EncodeKeys": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

如果默认（10 个文档）未充分利用或可用资源不堪重负，则设置“batchSize”。默认批大小特定于数据源。文件索引将批大小设置为 10 个文档，以识别较大的平均文档大小。
在“配置”下，根据文件类型控制对哪些文件编制索引，或者不指定以检索所有文件。

对于 "indexedFileNameExtensions"，请提供文件扩展名的逗号分隔列表（带前导点）。为 "excludedFileNameExtensions" 执行相同的操作来指定应跳过哪些扩展名。如果两个列表中存在同一个扩展名，则将其从索引编制中排除。
在“配置”下，设置“dataToExtract”以控制对文件的哪些部分编制索引：
- “contentAndMetadata”为默认。它指定对从文件中提取的所有元数据和文本内容编制索引。
- “storageMetadata”指定仅为标准文件属性和用户指定的元数据编制索引。尽管 Azure Blob 的属性是有文档记录的，但 OneLake 的文件属性是相同的，除了 SAS 相关元数据。
- “allMetadata”指定从文件内容中提取标准文件属性和任何已发现的内容类型的元数据，并为它们编制索引。
在“配置”下，如果文件应映射到多个搜索文档，或者如果它们由纯文本、JSON 文档或 CSV 文件组成，则设置“parsingMode”。
如果字段名称或类型存在差异，或者需要在搜索索引中使用多个版本的源字段，请指定字段映射。

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

有关其他属性的详细信息，请创建索引器。有关参数说明的完整列表，请参阅 REST API 中的创建索引器 (REST)。 OneLake 的参数相同。

默认情况下，索引器在创建时会自动运行。可以通过将“disabled”设置为 true 来更改此行为。若要控制索引器执行，请按需运行索引器或按计划运行索引器。

检查索引器状态

在此处了解监视索引器状态和执行历史记录的多种方法。

处理错误

索引期间经常发生的错误包括内容类型不受支持、缺少内容或文件太大。默认情况下，OneLake 文件索引器在遇到内容类型不受支持的文件时立即停止。但是，你可能会希望，即使发生错误索引编制也继续执行，你稍后再调试各个文档。

暂时性错误在涉及多个平台和产品的解决方案中很常见。但是，如果按计划保持索引器（例如每 5 分钟一次），则索引器应该能够在接下来的运行中从这些错误中恢复。

可以通过五个索引器属性控制索引器在出现错误时的响应。

{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
    }
  }
}

参数	有效值	说明
"maxFailedItems"	-1、null 或 0、正整数	如果在任意处理点（无论是在解析 blob 时，还是在将文档添加到索引时）发生错误，继续进行索引。将这些属性设置为可接受的失败数。如果值为 `-1`，则不管发生多少错误，都可以进行处理。否则，该值为正整数。
"maxFailedItemsPerBatch"	-1、null 或 0、正整数	与上面相同，但用于批处理索引编制。
"failOnUnsupportedContentType"	true 或 false	如果索引器无法确定内容类型，请指定是继续作业还是使作业失败。
"failOnUnprocessableDocument"	true 或 false	如果索引器无法处理其他受支持的内容类型的文档，请指定是继续作业还是使作业失败。
"indexStorageMetadataOnlyForOversizedDocuments"	true 或 false	过大的 blob 会被默认视为错误。如果将此参数设置为 true，则即使无法对内容编制索引，索引器也会尝试对其元数据进行索引。有关 blob 大小的限制，请参阅服务限制。

后续步骤

请查看导入和矢量化数据向导的工作方式，并在此索引器中试用它。可以使用集成矢量化来使用默认架构对矢量或混合搜索进行分块和创建嵌入。

通过