快速入門：使用 Bing 自動建議用戶端程式庫

發行項
04/06/2020

警告

2020 年 10 月 30 日，Bing 搜尋 API 已從 Azure AI 服務移至Bing 搜尋服務。本文件僅供參考之用。如需更新的文件，請參閱 Bing 搜尋 API 文件。如需針對 Bing 搜尋建立新 Azure 資源的指示，請參閱透過 Azure Marketplace 建立 Bing 搜尋資源。

開始使用適用於 .NET 的 Bing 自動建議用戶端程式庫。請遵循下列步驟來安裝套件，並試用基本工作的程式碼範例。

使用適用於 .NET 的 Bing 自動建議用戶端程式庫，以根據部分查詢字串來取得搜尋建議。

參考文件 | 程式庫來源程式碼 | 套件 (NuGet) | 範例程式碼

必要條件

Azure 訂用帳戶。如果您還沒有 Azure 訂用帳戶，您可以建立免費帳戶。
最新版 .NET Core。

建立 Azure 資源

藉由建立下列其中一項 Azure 資源，開始使用 Bing 自動建議 API。

Bing 自動建議資源

您可以透過 Azure 入口網站取得該資源，直到將其刪除為止。
使用免費定價層來試用服務，之後可升級至付費層以用於實際執行環境。
Bing 自動建議也會在 Bing 搜尋 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 或殼層，再重新加以開啟，才能存取該變數。

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 的 Bing 自動建議用戶端程式庫：

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

如果您使用 Visual Studio IDE，則可以取得可下載 NuGet 套件形式的用戶端程式庫。

程式碼範例

這些程式碼片段會示範如何使用適用於 .NET 的 Bing 自動建議用戶端程式庫來執行下列工作：

驗證用戶端
傳送自動建議要求

驗證用戶端

注意

本快速入門假設您已為 Bing 自動建議金鑰建立環境變數 (名為 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 方法，將查詢傳送至 Bing。然後，逐一查看建議回應，並列印第一個建議。

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 服務訂用帳戶，則可以刪除資源或資源群組。刪除資源群組也會刪除與其相關聯的任何其他資源：

後續步驟

Bing 自動建議教學課程l

另請參閱

開始使用適用於 Go 的 Bing 自動建議用戶端程式庫。請遵循下列步驟來安裝程式庫，並試用我們的基本工作範例。

使用適用於 Go 的 Bing 自動建議用戶端程式庫，以根據部分查詢字串來取得搜尋建議。

參考檔 | 範例程式碼

必要條件

Azure 訂用帳戶。如果您還沒有 Azure 訂用帳戶，您可以建立免費帳戶。
最新版的 Go。

藉由建立 Azure 資源，開始使用 Bing 自動建議用戶端程式庫。在下方選擇適合您的資源類型：

建立 Azure 資源

藉由建立下列其中一項 Azure 資源，開始使用 Bing 自動建議 API。

Bing 自動建議資源

您可以透過 Azure 入口網站取得該資源，直到將其刪除為止。
使用免費定價層來試用服務，之後可升級至付費層以用於實際執行環境。
Bing 自動建議也會在 Bing 搜尋 v7 資源的付費層中提供。

多服務資源

您可以透過 Azure 入口網站取得該資源，直到將其刪除為止。
針對您的應用程式，跨多個 Azure AI 服務使用相同的金鑰和端點。

建立環境變數

注意

在 2019 年 7 月 1 日之後建立的資源端點使用下面顯示的自訂子網域格式。如需詳細資訊和完整的區域端點清單，請參閱 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 的函式。然後，為 Bing 自動建議金鑰和端點建立環境變數：

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 的 Bing 自動建議用戶端程式庫來完成基本工作：

驗證用戶端
傳送 API 要求

驗證用戶端

注意

此快速入門假設您已為 Bing 自動建議金鑰建立環境變數 (名為 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 方法，將查詢傳送至 Bing。然後，逐一查看建議回應，並列印第一個建議。

// 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 服務訂用帳戶，則可以刪除資源或資源群組。刪除資源群組也會刪除其關聯的任何其他資源。

後續步驟

Bing 自動建議教學課程l