为 Azure Database for MySQL 灵活服务器中数据编制索引

本文将介绍如何配置索引器，该索引器从 Azure Database for MySQL 导入内容，并使内容在 Azure AI 搜索中可供搜索。 索引器的输入是单个表或视图中的行。 输出是一个搜索索引，其中的各个字段中具有可搜索内容。

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

当配置为包含高水位线和软删除时，索引器将接收 MySQL 数据库的所有更改、上传和删除。 它在您的搜索索引中反映了这些更改。 提交“创建索引器”请求时，将提取数据。

先决条件

• 注册预览版以提供方案反馈。 在提交表单后，你可以自动访问该功能。

• Azure Database for MySQL 灵活服务器和示例数据。 数据必须驻留在表或视图中。 主键是必需的。 如果使用的是视图，则它必须具有高水位线列。

• 读取权限。 “完全访问权限”连接字符串包含用于授予内容访问权限的密钥，但如果使用的是 Azure 角色，请确保搜索服务托管标识对 MySQL 具有“读取者”权限。

• 一个 REST 客户端，用于创建数据源、索引和索引器。

  还可以使用用于 .Net 的 Azure SDK。 无法通过 Azure 门户创建索引器，但可在创建索引器和数据源后，对其进行管理。

预览限制

目前，如果所有行的日期或时间戳都一致，则更改跟踪和删除检测无法正常工作。 这一限制一个已知问题，将在预览版更新中得到解决。 在解决此问题之前，请勿将技能组添加到 MySQL 索引器。

该预览版不支持几何类型和 blob。

如前所述，没有 Azure 门户支持创建索引器，但一旦 MySQL 索引器和数据源存在，就可以在门户中对其进行管理。 例如，可以编辑定义，然后重置、运行或计划索引器。

定义数据源

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

创建或更新数据源明确说明了该定义。 创建数据源时，请确保使用预览版 REST API。

{   
    "name" : "hotel-mysql-ds",
    "description" : "[Description of MySQL data source]",
    "type" : "mysql",
    "credentials" : { 
        "connectionString" : 
            "Server=[MySQLServerName].MySQL.database.azure.com; Port=3306; Database=[DatabaseName]; Uid=[UserName]; Pwd=[Password]; SslMode=Preferred;" 
    },
    "container" : { 
        "name" : "[TableName]" 
    },
    "dataChangeDetectionPolicy" : { 
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "[HighWaterMarkColumn]"
    }
}

要点：

• 将 type 设置为 "mysql"（必需）。

• 将 credentials 设置为 ADO.NET 连接字符串。 可以在 Azure 门户中 MySQL 的“连接字符串”页上找到连接字符串。

• 将 container 设置为表的名称。

• 如果数据经常变动，且你希望索引器在后续运行时只获取新项和更新的项，则设置 dataChangeDetectionPolicy。

• 如果要在删除源项时从搜索索引中删除搜索文档，则设置dataDeletionDetectionPolicy。

创建索引

创建或更新索引明确说明了索引架构：

{
    "name" : "hotels-mysql-ix",
    "fields": [
        { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false },
        { "name": "Category", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "City", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },
        { "name": "Description", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false  }     
    ]
}

如果源表中的主键与文档键（在本例中为 "ID"）匹配，则索引器将导入主键作为文档键。

映射数据类型

下表将 MySQL 数据库映射到Azure AI 搜索等效项。 有关详细信息，请参阅支持的数据类型（Azure AI 搜索）。

配置并运行 MySQL 索引器

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

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

{
    "name" : "hotels-mysql-idxr",
    "dataSourceName" : "hotels-mysql-ds",
    "targetIndexName" : "hotels-mysql-ix",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": null,
        "maxFailedItemsPerBatch": null,
        "base64EncodeKeys": null,
        "configuration": { }
        },
    "fieldMappings" : [ ],
    "encryptionKey": null
}

要点：

• 如果字段名称或类型存在差异，或者需要在搜索索引中使用多个版本的源字段，请指定字段映射。

• 创建索引器后，它会自动运行。 可以通过将 disabled 设置为 true 来阻止其运行。 若要控制索引器执行，请按需运行索引器或按计划运行索引器。

检查索引器状态

发送获取索引器状态请求以监视索引器执行：

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

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

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

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

为新行和已更改行编制索引

索引器完全填充搜索索引后，可能需要运行后续索引器，以便仅对数据库中的新行和已更改的行进行增量索引编制。

若要启用增量索引编制，请在数据源定义中设置 dataChangeDetectionPolicy 属性。 此属性告知索引器对数据使用哪种更改跟踪机制。

对于 Azure Database for MySQL 索引器，唯一支持的策略是 HighWaterMarkChangeDetectionPolicy。

索引器的更改检测策略依赖于一个高水位线列，该列用于记录行版本或上次更新行的日期和时间。 它通常是粒度足以满足高水位线列要求的 DATE、DATETIME 或 TIMESTAMP 列。

在 MySQL 数据库中，高水位线列必须满足以下要求：

• 所有数据插入都必须指定列值。
• 对某个项目的所有更新也会更改该列的值。
• 此列的值随每次插入或更新而增加。
• 具有以下 WHERE 和 ORDER BY 子句的查询可以高效执行：WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

以下示例演示具有更改检测策略的数据源定义：

{
    "name" : "[Data source name]",
    "type" : "mysql",
    "credentials" : { "connectionString" : "[connection string]" },
    "container" : { "name" : "[table or view name]" },
    "dataChangeDetectionPolicy" : {
        "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName" : "[last_updated column name]"
    }
}

为已删除的行编制索引

从表或视图中删除行时，通常还需要从搜索索引中删除这些行。 但如果以物理方式从表中删除行，索引器将无法推断出不再存在的记录是否存在。 解决方法是使用“软删除”技术以逻辑方式删除行，无需从表中删除它们。 将列添加到表或视图，并使用该列将行标记为已删除。

鉴于有一列提供删除状态，因此可以配置索引器，以将删除状态设置为 true 的搜索文档删除。 支持此行为的配置属性是数据删除检测策略，该策略在数据源定义中进行指定，如下所示：

{
    …,
    "dataDeletionDetectionPolicy" : {
        "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName" : "[a column name]",
        "softDeleteMarkerValue" : "[the value that indicates that a row is deleted]"
    }
}

softDeleteMarkerValue 必须是字符串。 例如，如果有一个整数列（使用值 1 标记删除的行），则使用 "1"。 如果有一个 BIT 列（使用布尔值 true 标记删除的行），请使用字符串字面量 True 或 true（不区分大小写）。

后续步骤

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

• 为大型数据集编制索引
• 索引器访问受 Azure 网络安全功能保护的内容