共用方式為

教程：使用 .NET SDK 为Azure SQL数据编制索引

了解如何配置 indexer 以从 Azure SQL Database 中提取可搜索数据并将其发送到Azure AI Search中的搜索索引。

本教程使用 C# 和 Azure SDK .NET：

  • 创建连接到Azure SQL Database的数据源
  • 创建索引器
  • 运行索引器以将数据载入索引
  • 作为验证步骤查询索引

先决条件

注意

可在本教程中使用免费搜索服务。 免费层限制为三个索引、三个索引器和三个数据源。 本教程将创建每种类型的一个示例。 在开始之前，请确保服务中有足够的空间来接受新资源。

下载文件

本教程的源代码位于 Azure-Samples/search-dotnet-getting-started GitHub 存储库中的 DotNetHowToIndexer 文件夹中。

创建服务

本教程使用Azure AI Search进行索引和查询，并使用Azure SQL Database作为外部数据源。 如果可能，请在同一区域和资源组中创建这两个服务，使它们相互靠近并易于管理。 在实践中，Azure SQL Database可以位于任何区域中。

从Azure SQL Database开始

本教程提供了示例下载中的 hotels.sql 文件来填充数据库。 Azure AI Search 使用展开的行集，例如从视图或查询生成的数据集。 示例解决方案中的 SQL 文件创建并填充单个表。

如果您已有 Azure SQL Database 资源，可以从 Open query 步骤开始向其中添加 hotels 表。

  1. 创建Azure SQL数据库。 数据库的服务器配置非常重要：

    • 选择提示你指定用户名和密码的SQL Server身份验证选项。 索引器使用的 ADO.NET connection string需要使用此属性。

    • 选择公共连接，使本教程更易于完成。 不建议将公共资源用于生产，建议在本教程结束时 删除此资源 。

    服务器配置的屏幕截图。

  2. 在Azure门户中，转到新资源。

  3. 添加允许从客户端访问的防火墙规则。 可以从命令提示符运行 ipconfig 以获取你的 IP 地址。

  4. 使用查询编辑器加载示例数据。 在导航窗格中，选择 “查询编辑器”（预览）， 并输入服务器管理员的用户名和密码。

    如果收到访问被拒错误，请从错误消息复制客户端 IP 地址，打开服务器的网络安全页，然后添加允许从你的客户端访问的入站规则。

  5. 在查询编辑器中选择“打开查询”，然后在本地计算机上导航到 hotels.sql 文件所在的位置。

  6. 选择该文件，然后选择“打开”。 此脚本应与以下屏幕截图类似：

    在查询编辑器窗口中的 SQL 脚本的屏幕截图。

  7. 选择“运行”以执行查询。 在“ 结果 ”窗格中，应会看到三行的查询成功消息。

  8. 若要从此表返回一个行集，可执行以下充当验证步骤的查询：

    SELECT * FROM Hotels

  9. 复制数据库的 ADO.NET 连接字符串。 在 Settings>Connection Strings 下，复制 ADO.NET connection string，应类似于以下示例：

    Server=tcp:<YOUR-DATABASE-NAME>.database.chinacloudapi.cn,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<YOUR-USER-NAME>;Password=<YOUR-PASSWORD>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;

在下一步中，您需要此连接字符串来设置您的环境。

下一个组件是Azure AI Search，可以在 Azure 门户中创建 。 可以使用免费层来完成本教程。

API 调用需要服务 URL 和访问密钥。 使用两者创建搜索服务，因此，如果将Azure AI Search添加到订阅，请按照以下步骤获取所需的信息：

  1. 登录到 Azure 门户。 在服务 概述 页上，复制终结点 URL。 示例终结点可能类似于 https://mydemo.search.azure.cn。

  2. 在“设置密钥”>上，获取服务完全权限的管理密钥。 有两个可交换的管理员密钥，为保证业务连续性而提供，以防需要滚动一个密钥。 可以对请求使用任一键来添加、修改或删除对象。

    Azure门户页面截图，显示搜索服务的HTTP终结点和访问密钥位置。

配置你的环境

  1. 启动Visual Studio并打开 DotNetHowToIndexers.sln。

  2. 在Solution Explorer中，打开 appsettings.json 以提供连接信息。

  3. 对于 SearchServiceEndPoint，如果您的服务概述页上的完整 URL 是https://my-demo-service.search.azure.cn，请提交该全部 URL。

  4. 对于 AzureSqlConnectionString，字符串格式类似于 "Server=tcp:<your-database-name>.database.chinacloudapi.cn,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<your-user-name>;Password=<your-password>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"。

    {
  "SearchServiceEndPoint": "<placeholder-search-full-url>",
  "SearchServiceAdminApiKey": "<placeholder-admin-key-for-search-service>",
  "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
}

  5. 将 SQL connection string中的用户密码替换为有效的密码。 数据库和用户名将被复制，但您必须手动输入密码。

创建管道

索引器需要数据源对象和索引。 相关代码在两个文件中：

  • hotel.cs 包含定义索引的架构
  • Program.cs 包含用于在服务中创建和管理结构的函数

在 hotel.cs 中

索引架构定义字段集合，包括指定允许作的属性，例如字段是可全文搜索、可筛选还是可排序，如以下字段定义 HotelName所示。 SearchableField 按定义可搜索全文。 其他属性被显式分配。

. . . 
[SearchableField(IsFilterable = true, IsSortable = true)]
[JsonPropertyName("hotelName")]
public string HotelName { get; set; }
. . .

模式还可以包含其他元素，例如用于提升搜索分数的评分配置文件和自定义分析器。 但是，在本教程中，架构是稀疏定义的，只包含示例数据集中找到的字段。

在 Program.cs 中

主程序包含用于创建索引器客户端、索引、数据源和索引器的逻辑。 代码检查并删除同名的现有资源，假设你可能多次运行此程序。

数据源对象配置了特定于Azure SQL Database资源的设置，包括部分索引或增量索引，用于利用 Azure SQL 内置的更改检测功能。 Azure SQL中的源演示酒店数据库具有名为 IsDeleted 的“软删除”列。 当此列在数据库中设置为 true 时，索引器将从Azure AI Search索引中删除相应的文档。

Console.WriteLine("Creating data source...");

var dataSource =
      new SearchIndexerDataSourceConnection(
         "hotels-sql-ds",
         SearchIndexerDataSourceType.AzureSql,
         configuration["AzureSqlConnectionString"],
         new SearchIndexerDataContainer("hotels"));

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

索引器对象与平台无关，无论源如何，配置、计划和调用都是相同的。 此示例索引器包括一个计划和一个重置选项，用于清除索引器历史记录。 它还调用方法以立即创建并运行索引器。 若要创建或更新索引器，请使用 CreateOrUpdateIndexerAsync。

Console.WriteLine("Creating Azure SQL indexer...");

var schedule = new IndexingSchedule(TimeSpan.FromDays(1))
{
      StartTime = DateTimeOffset.Now
};

var parameters = new IndexingParameters()
{
      BatchSize = 100,
      MaxFailedItems = 0,
      MaxFailedItemsPerBatch = 0
};

// Indexer declarations require a data source and search index.
// Common optional properties include a schedule, parameters, and field mappings
// The field mappings below are redundant due to how the Hotel class is defined, but 
// we included them anyway to show the syntax 
var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
      Description = "Data indexer",
      Schedule = schedule,
      Parameters = parameters,
      FieldMappings =
      {
         new FieldMapping("_id") {TargetFieldName = "HotelId"},
         new FieldMapping("Amenities") {TargetFieldName = "Tags"}
      }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

索引器运行通常是计划的，但在开发过程中，你可能希望使用 RunIndexerAsync 立即运行索引器。

Console.WriteLine("Running Azure SQL indexer...");

try
{
      await indexerClient.RunIndexerAsync(indexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
      Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

生成解决方案

选择 F5 以生成并运行解决方案。 程序在调试模式下执行。 控制台窗口报告每项操作的状态。

屏幕截图显示程序的控制台输出。

代码在Visual Studio本地运行，连接到Azure上的搜索服务，后者又连接到Azure SQL Database并检索数据集。 由于此处会发生多项操作，因此可能会造成多个故障点。 如果遇到错误，请先检查以下条件：

  • 你提供的搜索服务连接信息是完整的 URL。 如果您只输入服务名称，操作将在创建索引时停止，并出现连接失败错误。

  • appsettings.json 中的数据库连接信息。 它应该是从 Azure 门户获取的 ADO.NET connection string，修改为包含对数据库有效的用户名和密码。 用户帐户必须有权检索数据。 你的本地客户端 IP 地址必须能够通过防火墙进行入站访问。

  • 资源限制。 回想一下，免费层仅限三个索引、索引器和数据源。 达到最大限制的服务不能创建新的对象。

使用 Azure 门户验证对象创建，然后使用 Search 资源管理器查询索引。

  1. 在 Azure 门户中，转到你的搜索服务。

  2. 在左窗格中，打开每个页面以验证对象是否已创建。 索引、索引器和数据源应分别具有 hotels-sql-idx、hotels-sql-idxr 和 hotels-sql-ds。

  3. 在“ 索引 ”选项卡上，选择 hotels-sql-idx 索引。 在“酒店”页，“搜索资源管理器”是第一个选项卡。

  4. 选择搜索以执行空查询。

    索引中的三个条目以 JSON 文档的形式返回。 搜索浏览器返回 JSON 格式的文档，方便你查看整个结构。

    目标索引的搜索浏览器查询的屏幕截图。

  5. 切换到 JSON 视图 ，以便输入查询参数。

    {
     "search": "river",
     "count": true
}

    此查询调用字词 river的全文搜索。 结果包括匹配文档的计数。 返回匹配文档的计数在测试方案中非常有帮助，尤其是在拥有数千或数百万个文档的大型索引的情况下。 在本示例中，只有一个文档与查询匹配。

  6. 输入将搜索结果限制为感兴趣的字段的参数。

    {
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}

    查询响应范围缩小为选定字段，使输出更简洁。

重置并重新运行

在开发初期的实验阶段，设计迭代的最实用方法是从Azure AI Search中删除对象，并允许代码重新生成它们。 资源名称是唯一的。 删除某个对象后，可以使用相同的名称重新创建它。

本教程的示例代码将检查现有对象并将其删除，使你能够重新运行代码。

还可以使用 Azure 门户删除索引、索引器和数据源。

清理资源

在管理自己的订阅时，最好在项目结束时删除不再需要的资源。 持续运行资源可能会产生费用。 可以逐个删除资源，也可以删除资源组以删除整个资源集。

可以使用左侧导航窗格中的“所有资源”或“资源组”链接在Azure门户中查找和管理资源。

后续步骤

熟悉 SQL 数据库索引的基础知识后，请仔细了解索引器配置：

配置 SQL 数据库索引器

  • Last updated on