快速入门：使用必应自动建议客户端库

项目
04/06/2020

警告

2020 年 10 月 30 日，必应搜索 API 从 Azure AI 服务迁移到必应搜索服务。本文档仅供参考。有关更新的文档，请参阅必应搜索 API 文档。关于为必应搜索创建新的 Azure 资源的说明，请参阅通过 Azure 市场创建必应搜索资源。

开始使用适用于 .NET 的必应自动建议客户端库。请按照以下步骤安装程序包并试用基本任务的示例代码。

使用适用于 .NET 的必应自动建议客户端库，以便基于部分查询字符串获取搜索建议。

参考文档 | 库源代码 | 包 (NuGet) | 示例代码

先决条件

Azure 订阅。如果还没有 Azure 订阅，则可以免费创建一个。
.NET Core 的当前版本。

创建 Azure 资源

通过创建以下 Azure 资源之一开始使用必应自动建议 API。

必应自动建议资源

在删除资源前，可通过 Azure 门户使用。
使用免费定价层试用该服务，稍后升级到用于生产的付费层。
必应自动建议也在必应搜索 v7 资源的付费层中提供。

多服务资源

在删除资源前，可通过 Azure 门户使用。
在多个 Azure AI 服务中对应用程序使用相同的密钥和终结点。

创建环境变量

注意

在 2019 年 7 月 1 日之后创建的资源的终结点使用如下所示的自定义子域格式。有关详细信息和区域终结点的完整列表，请参阅 Azure AI 服务的自定义子域名。

从创建的资源使用密钥和终结点，创建两个用于身份验证的环境变量：

AUTOSUGGEST_SUBSCRIPTION_KEY：用于验证请求的资源密钥。
AUTOSUGGEST_ENDPOINT：用于发送 API 请求的资源终结点。它应如下所示： https://<your-custom-subdomain>.api.cognitive.microsoft.com。

使用操作系统的说明。

setx AUTOSUGGEST_SUBSCRIPTION_KEY <replace-with-your-autosuggest-api-key>
setx AUTOSUGGEST_ENDPOINT <replace-with-your-autosuggest-api-endpoint>

添加环境变量后，请重启控制台窗口。

export AUTOSUGGEST_SUBSCRIPTION_KEY=<replace-with-your-autosuggest-api-key>
export AUTOSUGGEST_ENDPOINT=<replace-with-your-autosuggest-api-endpoint>

添加环境变量后，请从控制台窗口运行 source ~/.bashrc，使更改生效。

编辑 .bash_profile，然后添加环境变量：

export AUTOSUGGEST_SUBSCRIPTION_KEY=<replace-with-your-autosuggest-api-key>
export AUTOSUGGEST_ENDPOINT=<replace-with-your-autosuggest-api-endpoint>

添加环境变量后，请从控制台窗口运行 source .bash_profile，使更改生效。

新建 C# 应用程序

在首选编辑器或 IDE 中创建新的 .NET Core 应用程序。

在控制台窗口（例如 cmd、PowerShell 或 Bash）中，使用 dotnet new 命令创建名为 bing-autosuggest-quickstart 的新控制台应用。此命令将创建包含单个源文件的简单“Hello World”C# 项目：program.cs。

dotnet new console -n bing-autosuggest-quickstart

将目录更改为新创建的应用文件夹。可使用以下代码生成应用程序：

dotnet build

生成输出不应包含警告或错误。

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

在首选的编辑器或 IDE 中，从项目目录打开 program.cs 文件。然后，添加以下 using 指令：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

在 Program 类中，为该资源的 Azure 终结点和密钥创建变量。如果在启动应用程序后创建了环境变量，则需要关闭再重新打开运行该应用程序的编辑器、IDE 或 shell 才能访问该变量。

private const string key_var = "AUTOSUGGEST_SUBSCRIPTION_KEY";
private static readonly string subscription_key = Environment.GetEnvironmentVariable(key_var);

// Note you must use the same region as you used to get your subscription key.
private const string endpoint_var = "AUTOSUGGEST_ENDPOINT";
private static readonly string endpoint = Environment.GetEnvironmentVariable(endpoint_var);

在应用程序的 Main 方法中，添加以下方法调用（稍后定义）。

static void Main(string[] args)
{
    Task.WaitAll(RunQuickstart());
    Console.WriteLine("Press any key to exit.");
    Console.Read();
}

安装客户端库

在应用程序目录中，使用以下命令安装适用于 .NET 的必应自动建议客户端库：

dotnet add package Microsoft.Azure.CognitiveServices.Search.AutoSuggest --version 2.0.0

如果你使用的是 Visual Studio IDE，客户端库可用作可下载的 NuGet 包。

代码示例

这些代码片段演示如何使用适用于 .NET 的必应自动建议客户端库执行以下任务：

对客户端进行身份验证
发送自动建议请求

验证客户端

注意

本快速入门假设你已为必应自动建议密钥创建了名为 AUTOSUGGEST_SUBSCRIPTION_KEY 的环境变量，以及一个用于终结点的名为 AUTOSUGGEST_ENDPOINT 的环境变量。

在新的异步方法中，使用终结点和密钥实例化客户端。使用密钥创建 ApiKeyServiceClientCredentials 对象，并在终结点中使用该对象创建一个 AutosuggestClient 对象。

async static Task RunQuickstart()
{
    // Generate the credentials and create the client.
    var credentials = new Microsoft.Azure.CognitiveServices.Search.AutoSuggest.ApiKeyServiceClientCredentials(subscription_key);
    var client = new AutoSuggestClient(credentials, new System.Net.Http.DelegatingHandler[] { })
    {
        Endpoint = endpoint
    };
}

发送自动建议请求

在同一方法中，使用客户端的 AutoSuggestMethodAsync 方法将查询发送到必应。然后，循环访问建议响应，并输出第一个建议。

var result = await client.AutoSuggestMethodAsync("xb");
var groups = result.SuggestionGroups;
if (groups.Count > 0) {
    var group = groups[0];
    Console.Write("First suggestion group: {0}\n", group.Name);
    var suggestions = group.SearchSuggestions;
    if (suggestions.Count > 0)
    {
        Console.WriteLine("First suggestion:");
        Console.WriteLine("Query: {0}", suggestions[0].Query);
        Console.WriteLine("Display text: {0}", suggestions[0].DisplayText);
    }
    else
    {
        Console.WriteLine("No suggestions found in this group.");
    }
}
else
{
    Console.WriteLine("No suggestions found.");
}

运行应用程序

从应用程序目录使用 dotnet run 命令运行应用程序。

dotnet run

清理资源

如果想要清理并移除 Azure AI 服务订阅，可以删除资源或资源组。删除资源组时也会删除与之关联的任何其他资源：

后续步骤

必应自动建议教程

另请参阅

开始使用适用于 Go 的必应自动建议客户端库。请按照以下步骤安装库并试用基本任务的示例。

使用适用于 Go 的必应自动建议客户端库，以便基于部分查询字符串获取搜索建议。

参考文档 | 示例代码

先决条件

Azure 订阅。如果还没有 Azure 订阅，则可以免费创建一个。
最新版本的 Go。

通过创建 Azure 资源，开始使用必应自动建议客户端库。选择下面适合你的资源类型：

创建 Azure 资源

通过创建以下 Azure 资源之一开始使用必应自动建议 API。

必应自动建议资源

在删除资源前，可通过 Azure 门户使用。
使用免费定价层试用该服务，稍后升级到用于生产的付费层。
必应自动建议也在必应搜索 v7 资源的付费层中提供。

多服务资源

在删除资源前，可通过 Azure 门户使用。
在多个 Azure AI 服务中对应用程序使用相同的密钥和终结点。

创建环境变量

注意

从创建的资源使用密钥和终结点，创建两个用于身份验证的环境变量：

AUTOSUGGEST_SUBSCRIPTION_KEY：用于验证请求的资源密钥。
AUTOSUGGEST_ENDPOINT：用于发送 API 请求的资源终结点。它应如下所示：https://<your-custom-subdomain>.api.cognitive.microsoft.com

使用操作系统的说明。

setx BING_AUTOSUGGEST_SUBSCRIPTION_KEY <replace-with-your-autosuggest-api-key>
setx BING_AUTOSUGGEST_ENDPOINT <replace-with-your-autosuggest-api-endpoint>

添加环境变量后，请重启控制台窗口。

export AUTOSUGGEST_SUBSCRIPTION_KEY=<replace-with-your-autosuggest-api-key>
export AUTOSUGGEST_ENDPOINT=<replace-with-your-autosuggest-api-endpoint>

添加环境变量后，请从控制台窗口运行 source ~/.bashrc，使更改生效。

编辑 .bash_profile，然后添加环境变量：

export AUTOSUGGEST_SUBSCRIPTION_KEY=<replace-with-your-autosuggest-api-key>
export AUTOSUGGEST_ENDPOINT=<replace-with-your-autosuggest-api-endpoint>

添加环境变量后，请从控制台窗口运行 source .bash_profile，使更改生效。

创建新的 Go 项目

在控制台窗口（cmd、PowerShell、终端、Bash）中，为 Go 项目创建一个新的工作区并导航到该工作区。工作区包含三个文件夹：

src：此目录包含源代码和包。使用 go get 命令安装的任何包将位于此处。
pkg：此目录包含已编译的 Go 包对象。这些文件使用 .a 扩展名。
bin：此目录包含运行 go install 时创建的二进制可执行文件。

提示

详细了解 Go 工作区的结构。本指南包含有关设置 $GOPATH 和 $GOROOT 的信息。

让我们创建名为 my-app 的工作区，并为 src、pkg 和 bin 创建所需的子目录：

$ mkdir -p my-app/{src, bin, pkg}  
$ cd my-app

安装适用于 Go 的客户端库

现在，让我们安装适用于 Go 的客户端库：

$ go get -u <library-location-or-url>

或者，如果使用 dep，则在存储库中运行：

$ dep ensure -add <library-location-or-url>

创建 Go 应用程序

接下来，让我们创建名为 src/sample-app.go 的文件：

$ cd src
$ touch sample-app.go

打开 sample-app.go，添加包名称，然后导入以下库：

package main

import (
    "context"
    "fmt"
    "github.com/Azure/azure-sdk-for-go/services/cognitiveservices/v1.0/autosuggest"
    "github.com/Azure/go-autorest/autorest"
    "log"
    "os"
)

创建一个名为 main 的函数。然后，为必应自动建议密钥和终结点创建环境变量：

func main() {
    // Add your Bing Autosuggest subscription key to your environment variables.
    if "" == os.Getenv("BING_AUTOSUGGEST_SUBSCRIPTION_KEY") {
        log.Fatal("Please set/export the environment variable BING_AUTOSUGGEST_SUBSCRIPTION_KEY.")
    }
    // Add your Bing Autosuggest endpoint to your environment variables.
    var subscription_key string = os.Getenv("BING_AUTOSUGGEST_ENDPOINT")
    if "" == os.Getenv("BING_AUTOSUGGEST_ENDPOINT") {
        log.Fatal("Please set/export the environment variable BING_AUTOSUGGEST_ENDPOINT.")
    }
    var endpoint string = os.Getenv("BING_AUTOSUGGEST_ENDPOINT")
}

代码示例

这些代码示例演示了如何使用适用于 Go 的必应自动建议客户端库来完成基本任务：

对客户端进行身份验证
发送 API 请求

验证客户端

注意

本快速入门假设你已为必应自动建议密钥创建了名为 BING_AUTOSUGGEST_SUBSCRIPTION_KEY 的环境变量，以及一个用于终结点的名为 BING_AUTOSUGGEST_ENDPOINT 的环境变量。

在 main() 函数中，使用终结点和密钥实例化客户端。

// Get the context, which is required by the SDK methods.
ctx := context.Background()

client := autosuggest.New()
// Set the subscription key on the client.
client.Authorizer = autorest.NewCognitiveServicesAuthorizer(subscription_key)
client.Endpoint = endpoint

发送 API 请求

在同一方法中，使用客户端的 AutoSuggestMethodAsync 方法将查询发送到必应。然后，循环访问建议响应，并输出第一个建议。

// This should return the query suggestion "xbox."
result, err := client.AutoSuggest (ctx, "xb", "", "", "", "", "", "", "", "", "", "", []autosuggest.ResponseFormat{"Json"})
if nil != err {
    log.Fatal(err)
}

groups := *result.SuggestionGroups
if len(groups) > 0 {
    group, _ := groups[0].AsSuggestionsSuggestionGroup()
    fmt.Printf ("First suggestion group: %s\n", (*group).Name)
    suggestions := *(*group).SearchSuggestions
    if len(suggestions) > 0 {
        fmt.Println("First suggestion:")
        fmt.Printf("Query: %s\n", *suggestions[0].Query)
        fmt.Printf("Display text: %s\n", *suggestions[0].DisplayText)
    } else {
        fmt.Println("No suggestions found in this group.")
    }
} else {
    fmt.Println("No suggestions found.")
}

运行应用程序

从应用程序目录使用 go run [arguments] 命令运行 Go 应用程序。

go run sample-app.go

清理资源

如果想要清理并移除 Azure AI 服务订阅，可以删除资源或资源组。删除资源组同时也会删除与之相关联的任何其他资源。

后续步骤

必应自动建议教程