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

Azure 认知搜索适用于 .NET 的客户端库 - 版本 11.4.0

项目
04/18/2023

Azure 认知搜索是一种搜索即服务云解决方案，它为开发人员提供 API 和工具，以便基于 Web、移动和企业应用程序中的专用异类内容添加丰富的搜索体验。

Azure 认知搜索服务非常适合以下应用程序方案：

将各种内容类型合并到单个可搜索索引中。若要填充索引，可以推送包含内容的 JSON 文档，或者，如果数据已在 Azure 中，请创建索引器以自动拉入数据。
将技能集附加到索引器，以从图像和大型文本文档创建可搜索的内容。技能组利用认知服务中的 AI 进行内置 OCR、实体识别、关键短语提取、语言检测、文本翻译和情绪分析。还可以添加自定义技能，以在数据引入期间集成内容的外部处理。
在搜索客户端应用程序中，实现类似于商业 Web 搜索引擎的查询逻辑和用户体验。

使用 Azure.Search.Documents 客户端库可以：

提交简单和高级查询表单的查询，包括模糊搜索、通配符搜索和正则表达式。
为分面导航、地理空间搜索或根据筛选条件缩小结果范围实施筛选查询。
创建和管理搜索索引。
上传和更新搜索索引中的文档。
创建和管理用于将数据从 Azure 拉取到索引中的索引器。
创建和管理将 AI 扩充添加到数据引入的技能集。
为高级文本分析或多语言内容创建和管理分析器。
通过计分配置文件优化结果，以考虑业务逻辑或新鲜度。

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 认知搜索客户端库：

dotnet add package Azure.Search.Documents

先决条件

需要 Azure 订阅和搜索服务才能使用此包。

若要创建新的搜索服务，可以使用 Azure 门户、Azure PowerShell 或 Azure CLI。下面是使用 Azure CLI 创建免费实例以开始使用的示例：

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

有关可用选项的详细信息，请参阅选择定价层。

验证客户端

对搜索服务的所有请求都需要专为服务生成的 API 密钥。 api-key 是验证对搜索服务终结点的访问的唯一机制。可以从 Azure 门户或通过 Azure CLI 获取 API 密钥：

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

有两种类型的密钥用于访问搜索服务： 管理员 (读写) 和查询 (只读) 密钥。限制客户端应用中的访问和操作对于保护服务中的搜索资产至关重要。对于源自客户端应用的任何查询，请始终使用查询密钥而不是管理密钥。

注意：上面的示例 Azure CLI 代码片段检索管理密钥，因此可以更轻松地开始探索 API，但应谨慎管理。

可以使用 api-key 创建新的 SearchClient。

string indexName = "nycjobs";

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

ASP.NET Core

若要在 ASP.NET Core应用中作为依赖项注入SearchClient，请先安装包 Microsoft.Extensions.Azure。然后在方法中 Startup.ConfigureServices 注册客户端：

public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureClients(builder =>
    {
        builder.AddSearchClient(Configuration.GetSection("SearchClient"));
    });
  
    services.AddControllers();
}

若要使用上述代码，请将此代码添加到配置中：

{
    "SearchClient": {
      "endpoint": "https://<resource-name>.search.windows.net",
      "indexname": "nycjobs"
    }
}

你还需要提供资源密钥来对客户端进行身份验证，但不应在配置中放置该信息。相反，在开发时，请使用用户机密。将下列内容添加到 secrets.json：

{
    "SearchClient": {
      "credential": { "key": "<you resource key>" }
    }
}

在生产环境中运行时，最好使用环境变量：

SEARCH__CREDENTIAL__KEY="..."

或者使用其他安全的方式来存储机密，例如 Azure 密钥保管库。

有关 ASP.NET Core 应用中的依赖关系注入的详细信息，请参阅使用 Azure SDK for .NET 进行依赖关系注入。

关键概念

Azure 认知搜索服务包含一个或多个索引，这些索引以 JSON 文档的形式提供可搜索数据的持久存储。 (如果你不熟悉搜索，可以在索引和数据库表之间进行非常粗略的类比。) Azure.Search.Documents 客户端库通过三种main客户端类型公开对这些资源的操作。

SearchClient 有助于：
- 使用丰富的查询和强大的数据整形来搜索索引文档
- 基于索引中的文档自动完成部分键入的搜索词
- 在用户键入时建议文档中最匹配的文本
- 在索引中添加、更新或删除文档文档
使用 SearchIndexClient，你可以：
- 创建、删除、更新或配置搜索索引
- 声明自定义同义词映射以扩展或重写查询
使用 SearchIndexerClient，你可以：
- 创建索引器以自动爬网数据源
- 定义 AI 支持的技能组以转换和扩充数据

Azure.Search.Documents (v11) 客户端库是面向想要在其应用程序中使用搜索技术的 .NET 开发人员的全新产品/服务。 (v10) 有一个功能齐全的 Microsoft.Azure.Search 较旧客户端库，其中包含许多外观相似的 API，因此在浏览联机资源时请小心避免混淆。一个很好的经验法则是在查找我们时为命名空间using Azure.Search.Documents;检查。

线程安全

我们保证所有客户端实例方法都是线程安全的，并且彼此独立 (准则) 。这可确保重用客户端实例的建议始终是安全的，即使在线程之间也是如此。

其他概念

示例

以下示例都使用简单的 Hotel 数据集，可以从Azure 门户导入到自己的索引中。这些只是一些基础知识 - 请检查我们的示例获取更多内容。

查询
创建索引
将文档添加到索引
从索引中检索特定文档
异步 API

高级身份验证

创建可在国家云中进行身份验证的客户端

查询

让我们首先导入命名空间。

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

然后，我们将创建一个 SearchClient 来访问我们的酒店搜索索引。

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
string indexName = "hotels";

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

可通过两种方式与从搜索查询返回的数据进行交互。让我们通过搜索“豪华”酒店来探索它们。

对搜索结果使用 C# 类型

可以使用中的System.Text.Json属性修饰自己的 C# 类型：

public class Hotel
{
    [JsonPropertyName("HotelId")]
    [SimpleField(IsKey = true, IsFilterable = true, IsSortable = true)]
    public string Id { get; set; }

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

然后在查询时将它们用作类型参数，以返回强类型搜索结果：

SearchResults<Hotel> response = client.Search<Hotel>("luxury");
foreach (SearchResult<Hotel> result in response.GetResults())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

如果使用搜索索引并了解架构，建议创建 C# 类型。

将 `SearchDocument` like 字典用于搜索结果

如果没有自己的搜索结果类型， SearchDocument 可以改用。在这里，我们将执行搜索，枚举结果，并使用 SearchDocument的字典索引器提取数据。

SearchResults<SearchDocument> response = client.Search<SearchDocument>("luxury");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    SearchDocument doc = result.Document;
    string id = (string)doc["HotelId"];
    string name = (string)doc["HotelName"];
    Console.WriteLine("{id}: {name}");
}

SearchOptions

SearchOptions提供对查询行为的强大控制。让我们搜索评级良好的前 5 家豪华酒店。

int stars = 4;
SearchOptions options = new SearchOptions
{
    // Filter to only Rating greater than or equal our preference
    Filter = SearchFilter.Create($"Rating ge {stars}"),
    Size = 5, // Take only 5 results
    OrderBy = { "Rating desc" } // Sort by Rating from high to low
};
SearchResults<Hotel> response = client.Search<Hotel>("luxury", options);
// ...

创建索引

可以使用 SearchIndexClient 创建搜索索引。可以使用 FieldBuilder 通过模型类来定义字段。索引还可以定义建议器、词法分析器等：

Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a service client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchIndexClient client = new SearchIndexClient(endpoint, credential);

// Create the index using FieldBuilder.
SearchIndex index = new SearchIndex("hotels")
{
    Fields = new FieldBuilder().Build(typeof(Hotel)),
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")
    }
};

client.CreateIndex(index);

在模型未知或无法修改的情况下，还可以使用方便 SimpleField的、 SearchableField或 ComplexField 类显式创建字段：

// Create the index using field definitions.
SearchIndex index = new SearchIndex("hotels")
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("tags", collection: true) { IsFilterable = true, IsFacetable = true },
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    },
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")
    }
};

client.CreateIndex(index);

将文档添加到索引

可以在UploadMerge单个批处理请求中从索引、、 MergeOrUpload和Delete多个文档。需要注意一些特殊的合并规则。

IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
    IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
    IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));

IndexDocumentsOptions options = new IndexDocumentsOptions { ThrowOnAnyError = true };
client.IndexDocuments(batch, options);

即使任何单个操作失败，请求也会成功，并返回以供 IndexDocumentsResult 检查。如果只关心整个批次的成功或失败，还有一个选项 ThrowOnAnyError 。

从索引中检索特定文档

除了使用关键字和可选筛选器查询文档外，如果已知道关键字，还可以从索引中检索特定文档。例如，可以从查询中获取密钥，并希望显示有关它的详细信息或将客户导航到该文档。

Hotel doc = client.GetDocument<Hotel>("1");
Console.WriteLine($"{doc.Id}: {doc.Name}");

异步 API

到目前为止，所有示例都使用同步 API，但我们也提供对异步 API 的完全支持。通常只需将后 Async 缀添加到方法的名称及其 await 上。

SearchResults<Hotel> response = await client.SearchAsync<Hotel>("luxury");
await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

在国家云中进行身份验证

若要在国家云中进行身份验证，需要对客户端配置进行以下添加：

在AuthorityHost凭据选项中或通过环境变量设置AZURE_AUTHORITY_HOST
在中 Audience 设置 SearchClientOptions

// Create a SearchClient that will authenticate through AAD in the China national cloud
string indexName = "nycjobs";
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
SearchClient client = new SearchClient(endpoint, indexName,
    new DefaultAzureCredential(
        new DefaultAzureCredentialOptions()
        {
            AuthorityHost = AzureAuthorityHosts.AzureChina
        }),
    new SearchClientOptions()
    {
        Audience = SearchAudience.AzureChina
    });

故障排除

任何失败的 Azure.Search.Documents 操作都将引发包含 RequestFailedException 有用 Status 代码的。其中许多错误是可恢复的。

try
{
    return client.GetDocument<Hotel>("12345");
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine("We couldn't find the hotel you are looking for!");
    Console.WriteLine("Please try selecting another.");
    return null;
}

如果想要更深入地了解针对服务发出的请求，还可以轻松启用控制台记录。

有关如何诊断各种故障方案的详细信息，请参阅故障排除指南。

后续步骤

进一步了解 Azure.Search.Documents 和我们的示例
观看演示或深入探讨视频
详细了解Azure 认知搜索服务

供稿

有关构建、测试和参与此库的详细信息，请参阅搜索 CONTRIBUTING.md 。

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

通过

Azure 认知搜索适用于 .NET 的客户端库 - 版本 11.4.0

入门

安装包

先决条件

验证客户端

ASP.NET Core

关键概念

线程安全

其他概念

示例

高级身份验证

查询

对搜索结果使用 C# 类型

将 `SearchDocument` like 字典用于搜索结果

SearchOptions

创建索引

将文档添加到索引

从索引中检索特定文档

异步 API

在国家云中进行身份验证

故障排除

后续步骤

供稿

反馈

其他资源

通过

Azure 认知搜索适用于 .NET 的客户端库 - 版本 11.4.0

入门

安装包

先决条件

验证客户端

ASP.NET Core

关键概念

线程安全

其他概念

示例

高级身份验证

查询

对搜索结果使用 C# 类型

将 SearchDocument like 字典用于搜索结果

SearchOptions

创建索引

将文档添加到索引

从索引中检索特定文档

异步 API

在国家云中进行身份验证

故障排除

后续步骤

供稿

反馈

其他资源

将 `SearchDocument` like 字典用于搜索结果