在 Azure AI 搜索中使用 Azure 存储索引器执行更改检测和删除检测

2025-10-24

创建初始搜索索引后，你可能希望后续索引器作业仅选取新的和已更改的文档。对于源自 Azure 存储的索引内容，更改检测会自动进行，因为索引器使用 Azure 存储中对象和文件的内置时间戳跟踪上次更新。

虽然更改检测是指定的，但删除检测不是。索引器不会跟踪数据源中的对象删除。若要避免具有孤立搜索文档，可以实施“软删除”策略，这会导致先删除搜索文档（在 Azure 存储中进行物理删除作为第二步）。

可通过两种方法实现软删除策略：

Blob 原生软删除，仅适用于 Blob 存储
使用自定义元数据的软删除

必须从恰好第一个索引器运行开始应用删除检测策略。如果在初始运行之前未建立删除策略，则实施策略之前删除的任何文档都将保留在索引中，即使稍后将策略添加到索引器并重置它也是如此。如果发生这种情况，建议使用新的索引器创建新索引，确保从头开始执行删除策略。

先决条件

对 Blob 存储、表存储、文件存储或 Data Lake Storage Gen2 使用 Azure 存储索引器
使用一致的文档键和文件结构。更改文档键或目录名称和路径（适用于 ADLS Gen2）会破坏索引器用来了解哪些内容编制了索引及其上次编制索引的时间的内部跟踪信息。

注释

ADLS Gen2 允许重命名目录。重命名目录时，该目录中 Blob 的时间戳不会更新。因此，索引器不会对这些 Blob 重新编制索引。如果需要在目录重命名之后重新编制索引目录中的 blob（因为它们现在有新的 URL），则需更新目录中所有 blob 的 LastModified 时间戳，使索引器知道在以后运行时将其重新编制索引。 Azure Blob 存储中的虚拟目录无法更改，因此它们没有此问题。

本机 Blob 软删除

对于这种删除检测方法，Azure AI 搜索依赖于 Azure Blob 存储中的本机 blob 软删除功能来确定 blob 是否已转换为软删除状态。如果在此状态下检测到 blob，搜索索引器将使用此信息从索引中删除相应的文档。

本机软删除的要求

Blob 必须位于 Azure Blob 存储容器中，包括 ADLS Gen2 Blob 容器。 Azure 文件存储不支持 Azure AI 搜索原生 Blob 软删除策略。
为 blob 启用软删除。
索引中文档的文档键必须映射到 Blob 属性或 Blob 元数据，例如“metadata_storage_path”。
可以使用 Azure 门户中的 REST API 或索引器数据源配置来配置对软删除的支持。
不得在存储帐户中启用 Blob 版本控制。否则，设计不支持本机软删除。

配置本机软删除

在 Blob 存储中，当根据需求启用软删除时，请将保留策略设置为明显高于索引器间隔计划的值。如果在运行索引器时出现问题，或者如果有大量的文档需要编制索引，可以为索引器留出大量的时间来最终处理已软删除的 Blob。仅当 Azure AI 搜索索引器在处理处于“已软删除”状态的 Blob 时，才会从索引中删除文档。

在 Azure AI 搜索中，在数据源中设置本机 Blob 软删除检测策略。可以从 Azure 门户或使用 REST API 执行此作。以下说明介绍如何在 Azure 门户中或通过 REST API 设置删除检测策略。

Azure 门户
REST

登录到 Azure 门户。
在 Azure AI 搜索服务概述页面上，转到“新数据源”，这是一个用于指定数据源定义的可视化编辑器。

以下屏幕截图显示了可在 Azure 门户中的哪里找到此功能。
在“新数据源”窗体上，填写必填字段，选中“跟踪删除”复选框并选择“本机 Blob 软删除”。然后点击“保存”，在创建数据源时启用该功能。

在数据源定义中设置软删除检测策略。在创建或更新数据源时指定 API 版本。

PUT https://[service name].search.azure.cn/datasources/blob-datasource?api-version=2025-09-01
Content-Type: application/json
api-key: [admin key]
{
   "name" : "blob-datasource",
   "type" : "azureblob",
   "credentials" : { "connectionString" : "<your storage connection string>" },
   "container" : { "name" : "my-container", "query" : null },
   "dataDeletionDetectionPolicy" : {
   "@odata.type" :"#Microsoft.Azure.Search.NativeBlobSoftDeleteDeletionDetectionPolicy"
   }
}

运行索引器，或者将索引器设置为按计划运行。当索引器运行并处理软删除状态的 blob 时，相应的搜索文档将从索引中删除。

通过本机软删除策略对取消删除的 Blob 重新编制索引

如果在 Blob 存储中还原软删除的 blob，则索引器不会始终对其重新编制索引。这是因为索引器使用 blob 的 LastModified 时间戳来确定是否需要编制索引。取消删除某个已软删除的 Blob 时，该 Blob 的 LastModified 时间戳不会更新，因此，如果索引器已处理的 Blob 的 LastModified 时间戳更接近当前时间，则索引器不会为这个取消删除的 Blob 重新编制索引。

若要确保为取消删除的 Blob 重新编制索引，需要更新该 Blob 的 LastModified 时间戳。为此，可以重新保存该 Blob 的元数据。你无需更改元数据，但重新保存元数据会更新 Blob 的 LastModified 时间戳，使索引器知道要选取它。

使用自定义元数据的软删除策略

此方法使用自定义元数据来指示是否应从索引中删除搜索文档。它需要两项单独的操作，即首先从索引中删除搜索文档，然后删除 Azure 存储中的文件。

此功能现已对所有用户开放使用。

有要在 Azure 存储和 Azure AI 搜索中执行的步骤，但没有其他功能依赖项。

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

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

PUT https://[service name].search.azure.cn/datasources/file-datasource?api-version=2025-09-01
{
    "name" : "file-datasource",
    "type" : "azurefile",
    "credentials" : { "connectionString" : "<your storage connection string>" },
    "container" : { "name" : "my-share", "query" : null },
    "dataDeletionDetectionPolicy" : {
        "@odata.type" :"#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName" : "IsDeleted",
        "softDeleteMarkerValue" : "true"
    }
}

运行索引器。索引器处理文件并从搜索索引中删除文档后，你可以在 Azure 存储中删除相应的物理文件。

为未删除的 Blob 和文件重新编制索引

如果原始源文件在物理上仍然存在于 Azure 存储中，则可以撤消软删除。

更改 Azure 存储中的 Blob 或文件上的 "softDeleteMarkerValue" : "false"。
检查 Blob 或文件的 LastModified 时间戳，使其比上次运行的索引器更新。可以通过重新保存现有元数据来强制更新当前日期和时间。
运行索引器。

通过