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

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

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

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

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

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

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

源代码 | 包 (NuGet) | API 参考文档 | REST API 文档 | 产品文档 | 样品

入门

安装包

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

dotnet add package Azure.Search.Documents

先决条件

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

若要创建新的搜索服务,可以使用 Azure 门户Azure PowerShellAzure 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客户端类型公开对这些资源的操作。

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

线程安全

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

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 嘲笑 | 客户端生存期

示例

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

高级身份验证

查询

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

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的 、 SearchableFieldComplexField 类显式创建字段:

// 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单个批处理请求中从索引、、 MergeOrUploadDelete多个文档。 需要注意 一些特殊的合并规则

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;
}

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

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

后续步骤

供稿

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

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

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

曝光数