通过

快速入门：使用 Azure SDK 进行全文搜索

  • 项目

了解如何使用 Azure SDK 中的 Azure.Search.Documents 客户端库创建、加载和查询使用示例数据的搜索索引，实现全文搜索。 全文搜索使用 Apache Lucene 进行索引和查询，使用 BM25 排名算法对结果进行评分。

本快速入门包含以下 SDK 的步骤：

先决条件

  • 具有活动订阅的 Azure 帐户。 创建试用版订阅。

  • Azure AI 搜索服务。 如果还没有，请创建服务。 对于本快速入门，可以使用免费层。

  • 服务的 API 密钥和服务终结点。 登录到 Azure 门户并查找你的搜索服务。

    在“概述”部分，复制 URL 并将其保存到文本编辑器，以供后续步骤使用。。 示例终结点可能类似于 https://mydemo.search.azure.cn。

    在“设置”>“密钥”部分，复制并保存管理密钥，以获取创建和删除对象的完整权限。 有两个可互换的主要密钥和辅助密钥。 选择其中一个。

    获取 HTTP 终结点和访问密钥

创建、加载并查询索引

选择下一步要使用的编程语言。 Azure.Search.Documents 客户端库在适用于 .NET、Python、Java 和 JavaScript/Typescript 的 Azure SDK 中提供。

使用 Azure.Search.Documents 客户端库构建一款控制台应用程序，用来创建、加载程查询搜索索引。

或者，可以下载源代码，从已完成的项目着手，或按照这些步骤创建自己的项目。

设置你的环境

  1. 启动 Visual Studio 并为控制台应用创建新项目。

  2. 在“工具”>“NuGet 包管理器”中，选择“管理解决方案的 NuGet 包...”。

  3. 选择“浏览”。

  4. 搜索 Azure.Search.Documents 包，并选择 11.0 或更高版本。

  5. 选择安装”，将该程序集添加到你的项目和解决方案。

创建搜索客户端

  1. 在“Program.cs”中，将命名空间更改为 AzureSearch.SDK.Quickstart.v11，然后添加以下 using 指令。

    using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

  2. 复制以下代码以创建两个客户端。 SearchIndexClient 创建索引，SearchClient 加载并查询现有索引。 两者都需要服务终结点和管理员 API 密钥才能使用创建/删除权限进行身份验证。

    由于代码为你生成了 URI，因此只需在 serviceName 属性中指定搜索服务名称。

     static void Main(string[] args)
 {
     string serviceName = "<your-search-service-name>";
     string apiKey = "<your-search-service-admin-api-key>";
     string indexName = "hotels-quickstart";

     // Create a SearchIndexClient to send create/delete index commands
     Uri serviceEndpoint = new Uri($"https://{serviceName}.search.azure.cn/");
     AzureKeyCredential credential = new AzureKeyCredential(apiKey);
     SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, credential);

     // Create a SearchClient to load and query documents
     SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, credential);
     . . . 
 }

创建索引

本快速入门生成 Hotels 索引，你将在其中加载酒店数据并对其执行查询。 在此步骤中，定义索引中的字段。 每个字段定义都包含名称、数据类型以及确定如何使用该字段的属性。

在此示例中，为了简单和可读性，使用了 Azure.Search.Documents 库的同步方法。 但是，对于生产场景，应使用异步方法来保持应用程序的可缩放性和响应性。 例如，使用 CreateIndexAsync，而不是 CreateIndex。

  1. 向项目添加一个空的类定义：Hotel.cs

  2. 将以下代码复制到 Hotel.cs 以定义酒店文档的结构。 该字段的属性决定字段在应用程序中的使用方式。 例如，IsFilterable 属性必须分配给每个支持筛选表达式的字段。

    using System;
using System.Text.Json.Serialization;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

namespace AzureSearch.Quickstart
{
    public partial class Hotel
    {
        [SimpleField(IsKey = true, IsFilterable = true)]
        public string HotelId { get; set; }

        [SearchableField(IsSortable = true)]
        public string HotelName { get; set; }

        [SearchableField(AnalyzerName = LexicalAnalyzerName.Values.EnLucene)]
        public string Description { get; set; }

        [SearchableField(AnalyzerName = LexicalAnalyzerName.Values.FrLucene)]
        [JsonPropertyName("Description_fr")]
        public string DescriptionFr { get; set; }

        [SearchableField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public string Category { get; set; }

        [SearchableField(IsFilterable = true, IsFacetable = true)]
        public string[] Tags { get; set; }

        [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public bool? ParkingIncluded { get; set; }

        [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public DateTimeOffset? LastRenovationDate { get; set; }

        [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public double? Rating { get; set; }

        [SearchableField]
        public Address Address { get; set; }
    }
}

    在 Azure.Search.Documents 客户端库中，可以使用 SearchableField 和 SimpleField 来简化字段定义。 两者都是 SearchField 的派生形式，可能会简化你的代码：

    • SimpleField 可以是任何数据类型，始终不可搜索（全文搜索查询将忽略它），并且可检索（未隐藏）。 其他属性默认情况下处于关闭状态，但可以启用。 你可能会将 SimpleField 用于仅在筛选器、facet 或计分概要文件中使用的文档 ID 或字段。 如果是这样，请确保应用该方案所需的所有属性，例如为文档 ID 应用 IsKey = true。 有关详细信息，请参阅源代码中的 SimpleFieldAttribute.cs。

    • SearchableField 必须是字符串，并且始终可搜索、可检索。 其他属性默认情况下处于关闭状态，但可以启用。 因为此字段类型是可搜索的，所以它支持同义词和分析器属性的完整补集。 有关详细信息，请参阅源代码中的 SearchableFieldAttribute.cs。

    无论使用基本 SearchField API 还是任一帮助程序模型，都必须显式启用筛选器、facet 和排序属性。 例如，IsFilterable、IsSortable 和 IsFacetable 必须进行显式属性化，如上一示例所示。

  3. 向项目添加第二个空的类定义：Address.cs。 将以下代码复制到类中。

    using Azure.Search.Documents.Indexes;

 namespace AzureSearch.Quickstart
 {
     public partial class Address
     {
         [SearchableField(IsFilterable = true)]
         public string StreetAddress { get; set; }

         [SearchableField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
         public string City { get; set; }

         [SearchableField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
         public string StateProvince { get; set; }

         [SearchableField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
         public string PostalCode { get; set; }

         [SearchableField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
         public string Country { get; set; }
     }
 }

  4. 再创建两个类：Hotel.Methods.cs 和 Address.Methods.cs，以重写 ToString()。 这些类用于在控制台输出中呈现搜索结果。 本文未提供这些类的内容，但可以从 GitHub 中的文件里复制代码。

  5. 在 Program.cs 中，创建一个 SearchIndex 对象，然后调用 CreateIndex 方法来表示搜索服务中的索引。 此索引还包括一个 SearchSuggester 以便在指定字段上启用自动完成。

     // Create hotels-quickstart index
 private static void CreateIndex(string indexName, SearchIndexClient adminClient)
 {
     FieldBuilder fieldBuilder = new FieldBuilder();
     var searchFields = fieldBuilder.Build(typeof(Hotel));

     var definition = new SearchIndex(indexName, searchFields);

     var suggester = new SearchSuggester("sg", new[] { "HotelName", "Category", "Address/City", "Address/StateProvince" });
     definition.Suggesters.Add(suggester);

     adminClient.CreateOrUpdateIndex(definition);
 }

加载文档

Azure AI 搜索对存储在服务中的内容进行搜索。 在此步骤中，加载符合刚刚创建的酒店索引的 JSON 文档。

在 Azure AI 搜索中，搜索文档这一数据结构既是索引输入，也是查询输出。 文档输入从外部数据源获取，可能是数据库中的行、Blob 存储中的 blob 或磁盘上的 JSON 文档。 在此示例中，我们采用了快捷方式，并在代码本身中嵌入了四个酒店的 JSON 文档。

上传文档时，必须使用 IndexDocumentsBatch 对象。 IndexDocumentsBatch 对象包含 Actions 集合，其中每个操作均包含一个文档和一个属性，该属性用于指示 Azure AI 搜索要执行什么操作（upload、merge、delete 和 mergeOrUpload）。

  1. 在 Program.cs 中，创建文档和索引操作的数组，然后将该数组传递给 IndexDocumentsBatch。 以下文档符合 hotel 类定义的 hotels-quickstart 索引。

    // Upload documents in a single Upload request.
private static void UploadDocuments(SearchClient searchClient)
{
    IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
        IndexDocumentsAction.Upload(
            new Hotel()
            {
                HotelId = "1",
                HotelName = "Secret Point Motel",
                Description = "The hotel is ideally located on the main commercial artery of the city in the heart of Beijing. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make Beijing one of America's most attractive and cosmopolitan cities.",
                DescriptionFr = "L'hôtel est idéalement situé sur la principale artère commerciale de la ville en plein cœur de Beijing. A quelques minutes se trouve la place du temps et le centre historique de la ville, ainsi que d'autres lieux d'intérêt qui font de Beijing l'une des villes les plus attractives et cosmopolites de l'Amérique.",
                Category = "Boutique",
                Tags = new[] { "pool", "air conditioning", "concierge" },
                ParkingIncluded = false,
                LastRenovationDate = new DateTimeOffset(1970, 1, 18, 0, 0, 0, TimeSpan.Zero),
                Rating = 3.6,
                Address = new Address()
                {
                    StreetAddress = "677 5th Ave",
                    City = "Beijing",
                    StateProvince = "NY",
                    PostalCode = "10022",
                    Country = "USA"
                }
            }),
        IndexDocumentsAction.Upload(
            new Hotel()
            {
                HotelId = "2",
                HotelName = "Twin Dome Motel",
                Description = "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
                DescriptionFr = "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
                Category = "Boutique",
                Tags = new[] { "pool", "free wifi", "concierge" },
                ParkingIncluded = false,
                LastRenovationDate = new DateTimeOffset(1979, 2, 18, 0, 0, 0, TimeSpan.Zero),
                Rating = 3.60,
                Address = new Address()
                {
                    StreetAddress = "140 University Town Center Dr",
                    City = "Sarasota",
                    StateProvince = "FL",
                    PostalCode = "34243",
                    Country = "USA"
                }
            }),
        IndexDocumentsAction.Upload(
            new Hotel()
            {
                HotelId = "3",
                HotelName = "Triple Landscape Hotel",
                Description = "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services.",
                DescriptionFr = "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
                Category = "Resort and Spa",
                Tags = new[] { "air conditioning", "bar", "continental breakfast" },
                ParkingIncluded = true,
                LastRenovationDate = new DateTimeOffset(2015, 9, 20, 0, 0, 0, TimeSpan.Zero),
                Rating = 4.80,
                Address = new Address()
                {
                    StreetAddress = "3393 Peachtree Rd",
                    City = "Atlanta",
                    StateProvince = "GA",
                    PostalCode = "30326",
                    Country = "USA"
                }
            }),
        IndexDocumentsAction.Upload(
            new Hotel()
            {
                HotelId = "4",
                HotelName = "Sublime Cliff Hotel",
                Description = "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.",
                DescriptionFr = "Le sublime Cliff Hotel est situé au coeur du centre historique de sublime dans un quartier extrêmement animé et vivant, à courte distance de marche des sites et monuments de la ville et est entouré par l'extraordinaire beauté des églises, des bâtiments, des commerces et Monuments. Sublime Cliff fait partie d'un Palace 1800 restauré avec amour.",
                Category = "Boutique",
                Tags = new[] { "concierge", "view", "24-hour front desk service" },
                ParkingIncluded = true,
                LastRenovationDate = new DateTimeOffset(1960, 2, 06, 0, 0, 0, TimeSpan.Zero),
                Rating = 4.60,
                Address = new Address()
                {
                    StreetAddress = "7400 San Pedro Ave",
                    City = "San Antonio",
                    StateProvince = "TX",
                    PostalCode = "78216",
                    Country = "USA"
                }
            })
        );

    try
    {
        IndexDocumentsResult result = searchClient.IndexDocuments(batch);
    }
    catch (Exception)
    {
        // If for some reason any documents are dropped during indexing, you can compensate by delaying and
        // retrying. This simple demo just logs the failed document keys and continues.
        Console.WriteLine("Failed to index some of the documents: {0}");
    }
}

    初始化 IndexDocumentsBatch 对象后，可以通过对 SearchClient 对象调用 IndexDocuments 将其发送到索引。

  2. 将以下行添加到 Main()。 加载文档是使用 SearchClient 完成的，但此操作还需要对服务的管理员权限，通常与 SearchIndexClient 相关联。 设置此操作的一种方法是通过 SearchIndexClient（在本示例中为 adminClient）获取 SearchClient。

     SearchClient ingesterClient = adminClient.GetSearchClient(indexName);

 // Load documents
 Console.WriteLine("{0}", "Uploading documents...\n");
 UploadDocuments(ingesterClient);

  3. 由于这是一个按顺序运行所有命令的控制台应用，因此请在索引和查询之间添加 2 秒的等待时间。

    // Wait 2 seconds for indexing to complete before starting queries (for demo and console-app purposes only)
Console.WriteLine("Waiting for indexing...\n");
System.Threading.Thread.Sleep(2000);

    2 秒的延迟可对索引编制进行补偿（这是异步操作），这样可在执行查询之前对所有文档编制索引。 以延迟方式编写代码通常仅在演示、测试和示例应用程序中是必要的。

搜索索引

对第一个文档编制索引后，可立即获取查询结果，但索引的实际测试应等到对所有文档编制索引后进行。

此部分添加了两个功能：查询逻辑和结果。 对于查询，请使用 Search 方法。 此方法接受搜索文本（查询字符串）以及其他选项。

SearchResults 类表示结果。

  1. 在 Program.cs 中，创建 WriteDocuments 方法，以将搜索结果输出到控制台。

    // Write search results to console
private static void WriteDocuments(SearchResults<Hotel> searchResults)
{
    foreach (SearchResult<Hotel> result in searchResults.GetResults())
    {
        Console.WriteLine(result.Document);
    }

    Console.WriteLine();
}

private static void WriteDocuments(AutocompleteResults autoResults)
{
    foreach (AutocompleteItem result in autoResults.Results)
    {
        Console.WriteLine(result.Text);
    }

    Console.WriteLine();
}

  2. 创建 RunQueries 方法用于执行查询并返回结果。 结果是 Hotel 对象。 此示例显示了方法签名和第一个查询。 此查询演示了 Select 参数，通过该参数可以使用文档中的选定字段来编写结果。

    // Run queries, use WriteDocuments to print output
private static void RunQueries(SearchClient srchclient)
{
    SearchOptions options;
    SearchResults<Hotel> response;

    // Query 1
    Console.WriteLine("Query #1: Search on empty term '*' to return all documents, showing a subset of fields...\n");

    options = new SearchOptions()
    {
        IncludeTotalCount = true,
        Filter = "",
        OrderBy = { "" }
    };

    options.Select.Add("HotelId");
    options.Select.Add("HotelName");
    options.Select.Add("Address/City");

    response = srchclient.Search<Hotel>("*", options);
    WriteDocuments(response);

  3. 在第二个查询中，搜索某个术语，添加筛选器（用于选择评级大于 4 的文档），然后按评级降序排序。 筛选器是布尔表达式，该表达式通过索引中的 IsFilterable 字段求值。 筛选器查询包括或排除值。 同样，筛选器查询没有关联的相关性分数。

    // Query 2
Console.WriteLine("Query #2: Search on 'hotels', filter on 'Rating gt 4', sort by Rating in descending order...\n");

options = new SearchOptions()
{
    Filter = "Rating gt 4",
    OrderBy = { "Rating desc" }
};

options.Select.Add("HotelId");
options.Select.Add("HotelName");
options.Select.Add("Rating");

response = srchclient.Search<Hotel>("hotels", options);
WriteDocuments(response);

  4. 第三个查询演示了用于将全文搜索操作的范围限定为特定字段的 searchFields。

    // Query 3
Console.WriteLine("Query #3: Limit search to specific fields (pool in Tags field)...\n");

options = new SearchOptions()
{
    SearchFields = { "Tags" }
};

options.Select.Add("HotelId");
options.Select.Add("HotelName");
options.Select.Add("Tags");

response = srchclient.Search<Hotel>("pool", options);
WriteDocuments(response);

  5. 第四个查询演示了 facets，它可用于构建分面导航结构。

     // Query 4
 Console.WriteLine("Query #4: Facet on 'Category'...\n");

 options = new SearchOptions()
 {
     Filter = ""
 };

 options.Facets.Add("Category");

 options.Select.Add("HotelId");
 options.Select.Add("HotelName");
 options.Select.Add("Category");

 response = srchclient.Search<Hotel>("*", options);
 WriteDocuments(response);

  6. 在第五个查询中，返回一个特定文档。 文档查找是对结果集中的 OnClick 事件的典型响应。

     // Query 5
 Console.WriteLine("Query #5: Look up a specific document...\n");

 Response<Hotel> lookupResponse;
 lookupResponse = srchclient.GetDocument<Hotel>("3");

 Console.WriteLine(lookupResponse.Value.HotelId);

  7. 最后一个查询显示了“自动完成”的语法，它模拟部分用户输入，即“sa”，该输入解析为 sourceFields 中的两个可能的匹配项，与你在索引中定义的建议器相关联。

     // Query 6
 Console.WriteLine("Query #6: Call Autocomplete on HotelName that starts with 'sa'...\n");

 var autoresponse = srchclient.Autocomplete("sa", "sg");
 WriteDocuments(autoresponse);

  8. 已将 RunQueries 添加到 Main()。

    // Call the RunQueries method to invoke a series of queries
Console.WriteLine("Starting queries...\n");
RunQueries(srchclient);

// End the program
Console.WriteLine("{0}", "Complete. Press any key to end this program...\n");
Console.ReadKey();

前面的查询显示了在查询中匹配术语的多种方式：全文搜索、筛选器和自动完成。

全文搜索和筛选器是使用 SearchClient.Search 方法执行的。 搜索查询可在 searchText 字符串中传递，而筛选表达式则可在 SearchOptions 类的 Filter 属性中传递。 若要筛选但不搜索，只需传递 "*" 作为 Search 方法的 searchText 参数。 若要在不筛选的情况下进行搜索，请保持 Filter 属性未设置，或者根本不传入 SearchOptions 实例。

运行程序

按 F5 可重新生成应用并完整运行该程序。

输出包含 Console.WriteLine 中的消息，并添加了查询信息和结果。

清理资源

在自己的订阅中操作时，最好在项目结束时确定是否仍需要已创建的资源。 持续运行资源可能会产生费用。 可以逐个删除资源，也可以删除资源组以删除整个资源集。

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

如果使用的是免费服务，请记住只能设置三个索引、索引器和数据源。 可以在门户中删除单个项目，以不超出此限制。

下一步

在此快速入门中，你已完成一系列任务，即创建索引、使用文档加载索引并运行查询。 在不同的阶段，我们采用快捷方式来简化代码，从而实现可读性和可理解性。 现在你已熟悉了基本概念，请尝试在 Web 应用中调用 Azure AI 搜索 API 的教程。

教程：向 Web 应用添加搜索