快速入门：使用必应 Web 搜索客户端库

项目
10/19/2020

警告

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

使用必应 Web 搜索客户端库可以轻松地将必应 Web 搜索集成到 C# 应用程序中。本快速入门介绍如何实例化客户端、发送请求和输出响应。

想要马上查看代码？ GitHub 上提供了适用于 .NET 的必应搜索客户端库的示例。

先决条件

下面是在开始本快速入门之前需要准备好的项目：

创建 Azure 资源

通过创建以下 Azure 资源之一开始使用必应 Web 搜索 API：

必应搜索 v7 资源

在删除资源前，可通过 Azure 门户使用。
使用免费定价层试用该服务，稍后升级到用于生产的付费层。

多服务资源

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

创建项目并安装依赖项

提示

从 GitHub 获取作为 Visual Studio 解决方案的最新代码。

第一步是创建新的控制台项目。如需控制台项目设置方面的帮助，请参阅 Hello World -- 你的第一个程序（C# 编程指南）。若要在应用程序中使用必应 Web 搜索 SDK，需使用 NuGet 包管理器来安装 Microsoft.Azure.CognitiveServices.Search.WebSearch。

Web 搜索 SDK 包还安装：

Microsoft.Rest.ClientRuntime
Microsoft.Rest.ClientRuntime.Azure
Newtonsoft.Json

声明依赖项

在 Visual Studio 或 Visual Studio Code 中打开项目，然后导入以下依赖项：

using System;
using System.Collections.Generic;
using Microsoft.Azure.CognitiveServices.Search.WebSearch;
using Microsoft.Azure.CognitiveServices.Search.WebSearch.Models;
using System.Linq;
using System.Threading.Tasks;

创建项目基架

创建新的控制台项目时，应该已经创建应用程序的命名空间和类。程序应如下例所示：

namespace WebSearchSDK
{
    class YOUR_PROGRAM
    {

        // The code in the following sections goes here.

    }
}

在以下部分，我们会在该类中生成示例应用程序。

构造请求

以下代码构造搜索查询。

public static async Task WebResults(WebSearchClient client)
{
    try
    {
        var webData = await client.Web.SearchAsync(query: "Yosemite National Park");
        Console.WriteLine("Searching for \"Yosemite National Park\"");

        // Code for handling responses is provided in the next section...

    }
    catch (Exception ex)
    {
        Console.WriteLine("Encountered exception. " + ex.Message);
    }
}

处理响应

接下来，让我们添加一些对响应进行分析并输出结果的代码。将会输出第一个网页、图像、新闻文章和视频的 Name 和 Url（如果存在于响应对象中）。

if (webData?.WebPages?.Value?.Count > 0)
{
    // find the first web page
    var firstWebPagesResult = webData.WebPages.Value.FirstOrDefault();

    if (firstWebPagesResult != null)
    {
        Console.WriteLine("Webpage Results # {0}", webData.WebPages.Value.Count);
        Console.WriteLine("First web page name: {0} ", firstWebPagesResult.Name);
        Console.WriteLine("First web page URL: {0} ", firstWebPagesResult.Url);
    }
    else
    {
        Console.WriteLine("Didn't find any web pages...");
    }
}
else
{
    Console.WriteLine("Didn't find any web pages...");
}

/*
 * Images
 * If the search response contains images, the first result's name
 * and url are printed.
 */
if (webData?.Images?.Value?.Count > 0)
{
    // find the first image result
    var firstImageResult = webData.Images.Value.FirstOrDefault();

    if (firstImageResult != null)
    {
        Console.WriteLine("Image Results # {0}", webData.Images.Value.Count);
        Console.WriteLine("First Image result name: {0} ", firstImageResult.Name);
        Console.WriteLine("First Image result URL: {0} ", firstImageResult.ContentUrl);
    }
    else
    {
        Console.WriteLine("Didn't find any images...");
    }
}
else
{
    Console.WriteLine("Didn't find any images...");
}

/*
 * News
 * If the search response contains news articles, the first result's name
 * and url are printed.
 */
if (webData?.News?.Value?.Count > 0)
{
    // find the first news result
    var firstNewsResult = webData.News.Value.FirstOrDefault();

    if (firstNewsResult != null)
    {
        Console.WriteLine("\r\nNews Results # {0}", webData.News.Value.Count);
        Console.WriteLine("First news result name: {0} ", firstNewsResult.Name);
        Console.WriteLine("First news result URL: {0} ", firstNewsResult.Url);
    }
    else
    {
        Console.WriteLine("Didn't find any news articles...");
    }
}
else
{
    Console.WriteLine("Didn't find any news articles...");
}

/*
 * Videos
 * If the search response contains videos, the first result's name
 * and url are printed.
 */
if (webData?.Videos?.Value?.Count > 0)
{
    // find the first video result
    var firstVideoResult = webData.Videos.Value.FirstOrDefault();

    if (firstVideoResult != null)
    {
        Console.WriteLine("\r\nVideo Results # {0}", webData.Videos.Value.Count);
        Console.WriteLine("First Video result name: {0} ", firstVideoResult.Name);
        Console.WriteLine("First Video result URL: {0} ", firstVideoResult.ContentUrl);
    }
    else
    {
        Console.WriteLine("Didn't find any videos...");
    }
}
else
{
    Console.WriteLine("Didn't find any videos...");
}

声明 main 方法

在此应用程序中，main 方法包括了用来实例化客户端、验证 subscriptionKey 和调用 WebResults 的代码。请确保输入你的 Azure 帐户的有效订阅密钥，然后再继续。

static async Task Main(string[] args)
{
    var client = new WebSearchClient(new ApiKeyServiceClientCredentials("YOUR_SUBSCRIPTION_KEY"));

    await WebResults(client);

    Console.WriteLine("Press any key to exit...");
    Console.ReadKey();
}

运行应用程序

让我们运行应用程序！

dotnet run

定义函数并筛选结果

对必应 Web 搜索 API 进行首次调用以后，让我们看看一些函数，这些函数突出显示了用于优化查询和筛选结果的 SDK 功能。每个函数都可以添加到在上一部分创建的 C# 应用程序中。

限制必应返回的结果数

此示例使用 count 和 offset 参数限制针对“西雅图最好的餐馆”搜索返回的结果数。将会输出初始结果的 Name 和 Url。

将以下代码添加到控制台项目：

public static async Task WebResultsWithCountAndOffset(WebSearchClient client)
{
    try
    {
        var webData = await client.Web.SearchAsync(query: "Best restaurants in Seattle", offset: 10, count: 20);
        Console.WriteLine("\r\nSearching for \" Best restaurants in Seattle \"");

        if (webData?.WebPages?.Value?.Count > 0)
        {
            var firstWebPagesResult = webData.WebPages.Value.FirstOrDefault();

            if (firstWebPagesResult != null)
            {
                Console.WriteLine("Web Results #{0}", webData.WebPages.Value.Count);
                Console.WriteLine("First web page name: {0} ", firstWebPagesResult.Name);
                Console.WriteLine("First web page URL: {0} ", firstWebPagesResult.Url);
            }
            else
            {
                Console.WriteLine("Couldn't find first web result!");
            }
        }
        else
        {
            Console.WriteLine("Didn't see any Web data..");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Encountered exception. " + ex.Message);
    }
}

将 WebResultsWithCountAndOffset 添加到 main：

static async Task Main(string[] args)
{
    var client = new WebSearchClient(new ApiKeyServiceClientCredentials("YOUR_SUBSCRIPTION_KEY"));

    await WebResults(client);
    // Search with count and offset...
    await WebResultsWithCountAndOffset(client);  

    Console.WriteLine("Press any key to exit...");
    Console.ReadKey();
}

运行应用程序。

新闻筛选器

此示例使用 response_filter 参数筛选搜索结果。返回的搜索结果仅限“Microsoft”的新闻文章。将会输出初始结果的 Name 和 Url。

将以下代码添加到控制台项目：

public static async Task WebSearchWithResponseFilter(WebSearchClient client)
{
    try
    {
        IList<string> responseFilterstrings = new List<string>() { "news" };
        var webData = await client.Web.SearchAsync(query: "Microsoft", responseFilter: responseFilterstrings);
        Console.WriteLine("\r\nSearching for \" Microsoft \" with response filter \"news\"");

        if (webData?.News?.Value?.Count > 0)
        {
            var firstNewsResult = webData.News.Value.FirstOrDefault();

            if (firstNewsResult != null)
            {
                Console.WriteLine("News Results #{0}", webData.News.Value.Count);
                Console.WriteLine("First news result name: {0} ", firstNewsResult.Name);
                Console.WriteLine("First news result URL: {0} ", firstNewsResult.Url);
            }
            else
            {
                Console.WriteLine("Couldn't find first News results!");
            }
        }
        else
        {
            Console.WriteLine("Didn't see any News data..");
        }

    }
    catch (Exception ex)
    {
        Console.WriteLine("Encountered exception. " + ex.Message);
    }
}

将 WebResultsWithCountAndOffset 添加到 main：

static Task Main(string[] args)
{
    var client = new WebSearchClient(new ApiKeyServiceClientCredentials("YOUR_SUBSCRIPTION_KEY"));

    await WebResults(client);
    // Search with count and offset...
    await WebResultsWithCountAndOffset(client);  
    // Search with news filter...
    await WebSearchWithResponseFilter(client);

    Console.WriteLine("Press any key to exit...");
    Console.ReadKey();
}

运行应用程序。

使用安全搜索、答案计数和提升筛选器

此示例使用 answer_count、promote 和 safe_search 参数筛选“音乐视频”的搜索结果。将会显示初始结果的 Name 和 ContentUrl。

将以下代码添加到控制台项目：

public static async Task WebSearchWithAnswerCountPromoteAndSafeSearch(WebSearchClient client)
{
    try
    {
        IList<string> promoteAnswertypeStrings = new List<string>() { "videos" };
        var webData = await client.Web.SearchAsync(query: "Music Videos", answerCount: 2, promote: promoteAnswertypeStrings, safeSearch: SafeSearch.Strict);
        Console.WriteLine("\r\nSearching for \"Music Videos\"");

        if (webData?.Videos?.Value?.Count > 0)
        {
            var firstVideosResult = webData.Videos.Value.FirstOrDefault();

            if (firstVideosResult != null)
            {
                Console.WriteLine("Video Results # {0}", webData.Videos.Value.Count);
                Console.WriteLine("First Video result name: {0} ", firstVideosResult.Name);
                Console.WriteLine("First Video result URL: {0} ", firstVideosResult.ContentUrl);
            }
            else
            {
                Console.WriteLine("Couldn't find videos results!");
            }
        }
        else
        {
            Console.WriteLine("Didn't see any data..");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Encountered exception. " + ex.Message);
    }
}

将 WebResultsWithCountAndOffset 添加到 main：

static async Task Main(string[] args)
{
    var client = new WebSearchClient(new ApiKeyServiceClientCredentials("YOUR_SUBSCRIPTION_KEY"));

    await WebResults(client);
    // Search with count and offset...
    await WebResultsWithCountAndOffset(client);  
    // Search with news filter...
    await WebSearchWithResponseFilter(client);
    // Search with answer count, promote, and safe search
    await WebSearchWithAnswerCountPromoteAndSafeSearch(client);

    Console.WriteLine("Press any key to exit...");
    Console.ReadKey();
}

运行应用程序。

清理资源

完成本项目以后，请务必从应用程序代码中删除订阅密钥。

后续步骤

Azure AI 服务 Node.js SDK 示例

使用必应 Web 搜索客户端库可以轻松地将必应 Web 搜索集成到 Java 应用程序中。本快速入门介绍了如何发送请求、接收 JSON 响应以及筛选和分析结果。

想要马上查看代码？ GitHub 上提供了适用于 Java 的必应搜索客户端库的示例。

必备条件

下面是在开始本快速入门之前需要准备好的项目：

JDK 7 或 8
Apache Maven 或你喜欢使用的生成自动化工具
订阅密钥

创建 Azure 资源

通过创建以下 Azure 资源之一开始使用必应 Web 搜索 API：

必应搜索 v7 资源

在删除资源前，可通过 Azure 门户使用。
使用免费定价层试用该服务，稍后升级到用于生产的付费层。

多服务资源

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

创建一个项目并设置 POM 文件

使用 Maven 或你喜欢使用的生成自动化工具新建一个 Java 项目。假设你使用 Maven，请将以下行添加到项目对象模型 (POM) 文件。将 mainClass 的所有实例替换为你的应用程序。

<build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>1.4.0</version>
        <configuration>
          <!--Your comment
            Replace the mainClass with the path to your Java application.
            It should begin with com and doesn't require the .java extension.
            For example: com.bingwebsearch.app.BingWebSearchSample. This maps to
            The following directory structure:
            src/main/java/com/bingwebsearch/app/BingWebSearchSample.java.
          -->
          <mainClass>com.path.to.your.app.APP_NAME</mainClass>
        </configuration>
      </plugin>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.0</version>
        <configuration>
          <source>1.7</source>
          <target>1.7</target>
        </configuration>
      </plugin>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>attached</goal>
            </goals>
            <configuration>
              <descriptorRefs>
                <descriptorRef>jar-with-dependencies</descriptorRef>
              </descriptorRefs>
              <archive>
                <manifest>
                  <!--Your comment
                    Replace the mainClass with the path to your Java application.
                    For example: com.bingwebsearch.app.BingWebSearchSample.java.
                    This maps to the following directory structure:
                    src/main/java/com/bingwebsearch/app/BingWebSearchSample.java.
                  -->
                  <mainClass>com.path.to.your.app.APP_NAME.java</mainClass>
                </manifest>
              </archive>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  <dependencies>
    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>azure</artifactId>
      <version>1.9.0</version>
    </dependency>
    <dependency>
      <groupId>commons-net</groupId>
      <artifactId>commons-net</artifactId>
      <version>3.3</version>
    </dependency>
    <dependency>
      <groupId>com.microsoft.azure.cognitiveservices</groupId>
      <artifactId>azure-cognitiveservices-websearch</artifactId>
      <version>1.0.1</version>
    </dependency>
  </dependencies>

声明依赖项

在你喜欢使用的 IDE 或编辑器中打开你的项目，并导入以下依赖项：

import com.microsoft.azure.cognitiveservices.search.websearch.BingWebSearchAPI;
import com.microsoft.azure.cognitiveservices.search.websearch.BingWebSearchManager;
import com.microsoft.azure.cognitiveservices.search.websearch.models.ImageObject;
import com.microsoft.azure.cognitiveservices.search.websearch.models.NewsArticle;
import com.microsoft.azure.cognitiveservices.search.websearch.models.SearchResponse;
import com.microsoft.azure.cognitiveservices.search.websearch.models.VideoObject;
import com.microsoft.azure.cognitiveservices.search.websearch.models.WebPage;

如果项目是使用 Maven 创建的，则应当已经声明了此程序包。否则，现在请声明此程序包。例如：

package com.bingwebsearch.app

声明 BingWebSearchSample 类

声明 BingWebSearchSample 类。它将包括我们的大多数代码，包括 main 方法。

public class BingWebSearchSample {

// The code in the following sections goes here.

}

构造请求

runSample 方法（位于 BingWebSearchSample 类中）构造请求。将以下代码复制到你的应用程序中：

public static boolean runSample(BingWebSearchAPI client) {
    /*
     * This function performs the search.
     *
     * @param client instance of the Bing Web Search API client
     * @return true if sample runs successfully
     */
    try {
        /*
         * Performs a search based on the .withQuery and prints the name and
         * url for the first web pages, image, news, and video result
         * included in the response.
         */
        System.out.println("Searched Web for \"Xbox\"");
        // Construct the request.
        SearchResponse webData = client.bingWebs().search()
            .withQuery("Xbox")
            .withMarket("en-us")
            .withCount(10)
            .execute();

// Code continues in the next section...

处理响应

接下来，让我们添加一些对响应进行分析并输出结果的代码。将会输出第一个网页、图像、新闻文章和视频的 name 和 url（如果它们包括在响应对象中）。

/*
* WebPages
* If the search response has web pages, the first result's name
* and url are printed.
*/
if (webData != null && webData.webPages() != null && webData.webPages().value() != null &&
        webData.webPages().value().size() > 0) {
    // find the first web page
    WebPage firstWebPagesResult = webData.webPages().value().get(0);

    if (firstWebPagesResult != null) {
        System.out.println(String.format("Webpage Results#%d", webData.webPages().value().size()));
        System.out.println(String.format("First web page name: %s ", firstWebPagesResult.name()));
        System.out.println(String.format("First web page URL: %s ", firstWebPagesResult.url()));
    } else {
        System.out.println("Couldn't find the first web result!");
    }
} else {
    System.out.println("Didn't find any web pages...");
}
/*
 * Images
 * If the search response has images, the first result's name
 * and url are printed.
 */
if (webData != null && webData.images() != null && webData.images().value() != null &&
        webData.images().value().size() > 0) {
    // find the first image result
    ImageObject firstImageResult = webData.images().value().get(0);

    if (firstImageResult != null) {
        System.out.println(String.format("Image Results#%d", webData.images().value().size()));
        System.out.println(String.format("First Image result name: %s ", firstImageResult.name()));
        System.out.println(String.format("First Image result URL: %s ", firstImageResult.contentUrl()));
    } else {
        System.out.println("Couldn't find the first image result!");
    }
} else {
    System.out.println("Didn't find any images...");
}
/*
 * News
 * If the search response has news articles, the first result's name
 * and url are printed.
 */
if (webData != null && webData.news() != null && webData.news().value() != null &&
        webData.news().value().size() > 0) {
    // find the first news result
    NewsArticle firstNewsResult = webData.news().value().get(0);
    if (firstNewsResult != null) {
        System.out.println(String.format("News Results#%d", webData.news().value().size()));
        System.out.println(String.format("First news result name: %s ", firstNewsResult.name()));
        System.out.println(String.format("First news result URL: %s ", firstNewsResult.url()));
    } else {
        System.out.println("Couldn't find the first news result!");
    }
} else {
    System.out.println("Didn't find any news articles...");
}

/*
 * Videos
 * If the search response has videos, the first result's name
 * and url are printed.
 */
if (webData != null && webData.videos() != null && webData.videos().value() != null &&
        webData.videos().value().size() > 0) {
    // find the first video result
    VideoObject firstVideoResult = webData.videos().value().get(0);

    if (firstVideoResult != null) {
        System.out.println(String.format("Video Results#%s", webData.videos().value().size()));
        System.out.println(String.format("First Video result name: %s ", firstVideoResult.name()));
        System.out.println(String.format("First Video result URL: %s ", firstVideoResult.contentUrl()));
    } else {
        System.out.println("Couldn't find the first video result!");
    }
} else {
    System.out.println("Didn't find any videos...");
}

声明 main 方法

在此应用程序中，main 方法包括了用来实例化客户端、验证 subscriptionKey 和调用 runSample 的代码。请确保输入你的 Azure 帐户的有效订阅密钥，然后再继续。

public static void main(String[] args) {
    try {
        // Enter a valid subscription key for your account.
        final String subscriptionKey = "YOUR_SUBSCRIPTION_KEY";
        // Instantiate the client.
        BingWebSearchAPI client = BingWebSearchManager.authenticate(subscriptionKey);
        // Make a call to the Bing Web Search API.
        runSample(client);
    } catch (Exception e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

运行程序

最后一步是运行程序！

mvn compile exec:java

清理资源

完成本项目以后，请务必从程序代码中删除订阅密钥。

后续步骤

Azure AI 服务 Java SDK 示例

另请参阅

Azure Java SDK 参考

使用必应 Web 搜索客户端库可以轻松地将必应 Web 搜索集成到 Node.js 应用程序中。本快速入门介绍如何实例化客户端、发送请求和输出响应。

想要马上查看代码？ GitHub 上提供了适用于 JavaScript 的必应搜索客户端库的示例。

必备条件

下面是在开始本快速入门之前需要准备好的项目：

Node.js 6 或更高版本
订阅密钥

创建 Azure 资源

通过创建以下 Azure 资源之一开始使用必应 Web 搜索 API：

必应搜索 v7 资源

在删除资源前，可通过 Azure 门户使用。
使用免费定价层试用该服务，稍后升级到用于生产的付费层。

多服务资源

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

设置开发环境

让我们从设置 Node.js 项目的开发环境开始。

为项目新建一个目录：
```
mkdir YOUR_PROJECT
```
创建新的包文件：
```
cd YOUR_PROJECT
npm init
```

现在，让我们安装一些 Azure 模块并将它们添加到 package.json：

npm install --save @azure/cognitiveservices-websearch
npm install --save @azure/ms-rest-azure-js

创建一个项目并声明必需的模块

在 package.json 所在的目录中，使用喜欢的 IDE 或编辑器新建一个 Node.js 项目。例如：sample.js。

接下来，将以下代码复制到项目中。它会加载在上一部分安装的模块。

const CognitiveServicesCredentials = require('@azure/ms-rest-azure-js').CognitiveServicesCredentials;
const WebSearchAPIClient = require('@azure/cognitiveservices-websearch');

对客户端进行实例化

以下代码实例化一个客户端并使用 @azure/cognitiveservices-websearch 模块。请确保输入你的 Azure 帐户的有效订阅密钥，然后再继续。

let credentials = new CognitiveServicesCredentials('YOUR-ACCESS-KEY');
let webSearchApiClient = new WebSearchAPIClient(credentials);

发出请求并输出结果

使用客户端向必应 Web 搜索发送搜索查询。如果响应包含 properties 数组中任何项的结果，则会将 result.value 输出到控制台。

webSearchApiClient.web.search('seahawks').then((result) => {
    let properties = ["images", "webPages", "news", "videos"];
    for (let i = 0; i < properties.length; i++) {
        if (result[properties[i]]) {
            console.log(result[properties[i]].value);
        } else {
            console.log(`No ${properties[i]} data`);
        }
    }
}).catch((err) => {
    throw err;
})

运行程序

最后一步是运行程序！

清理资源

完成本项目以后，请务必从程序代码中删除订阅密钥。

后续步骤

Azure AI 服务 Node.js SDK 示例

另请参阅

Azure Node SDK 参考

使用必应 Web 搜索客户端库可以轻松地将必应 Web 搜索集成到 Python 应用程序中。本快速入门介绍了如何发送请求、接收 JSON 响应以及筛选和分析结果。

想要马上查看代码？ GitHub 上提供了适用于 Python 的必应搜索客户端库的示例。

先决条件

必应 Web 搜索 SDK 与 Python 2.7 或 3.6+ 兼容。建议在本快速入门中使用虚拟环境。

Python 2.7 或 3.6+
适用于 Python 2.7 的 virtualenv
适用于 Python 3.x 的 venv

创建 Azure 资源

通过创建以下 Azure 资源之一开始使用必应 Web 搜索 API：

必应搜索 v7 资源

在删除资源前，可通过 Azure 门户使用。
使用免费定价层试用该服务，稍后升级到用于生产的付费层。

多服务资源

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

创建并配置虚拟环境

Python 2.x 和 Python 3.x 的设置和配置虚拟环境的说明是不同的。请按以下步骤创建和初始化虚拟环境。

Python 2.x

使用 virtualenv 为 Python 2.7 创建虚拟环境：

virtualenv mytestenv

激活环境：

cd mytestenv
source bin/activate

安装必应 Web 搜索 SDK 依赖项：

python -m pip install azure-cognitiveservices-search-websearch

Python 3.x

使用 venv 为 Python 3.x 创建虚拟环境：

python -m venv mytestenv

激活环境：

mytestenv\Scripts\activate.bat

安装必应 Web 搜索 SDK 依赖项：

cd mytestenv
python -m pip install azure-cognitiveservices-search-websearch

创建客户端并输出初始结果

设置虚拟环境并安装依赖项之后，就可以创建客户端了。客户端会处理针对必应 Web 搜索 API 的请求以及来自该 API 的响应。

如果响应包含网页、图像、新闻或视频，则会输出各自的初始结果。

使用最喜欢的 IDE 或编辑器创建新的 Python 项目。

将此示例代码复制到项目中。 endpoint 可以是下面的全局终结点，也可以是资源的 Azure 门户中显示的自定义子域终结点。

# Import required modules.
from azure.cognitiveservices.search.websearch import WebSearchClient
from azure.cognitiveservices.search.websearch.models import SafeSearch
from msrest.authentication import CognitiveServicesCredentials

# Replace with your subscription key.
subscription_key = "YOUR_SUBSCRIPTION_KEY"

# Instantiate the client and replace with your endpoint.
client = WebSearchClient(endpoint="YOUR_ENDPOINT", credentials=CognitiveServicesCredentials(subscription_key))

# Make a request. Replace Yosemite if you'd like.
web_data = client.web.search(query="Yosemite")
print("\r\nSearched for Query# \" Yosemite \"")

'''
Web pages
If the search response contains web pages, the first result's name and url
are printed.
'''
if hasattr(web_data.web_pages, 'value'):

    print("\r\nWebpage Results#{}".format(len(web_data.web_pages.value)))

    first_web_page = web_data.web_pages.value[0]
    print("First web page name: {} ".format(first_web_page.name))
    print("First web page URL: {} ".format(first_web_page.url))

else:
    print("Didn't find any web pages...")

'''
Images
If the search response contains images, the first result's name and url
are printed.
'''
if hasattr(web_data.images, 'value'):

    print("\r\nImage Results#{}".format(len(web_data.images.value)))

    first_image = web_data.images.value[0]
    print("First Image name: {} ".format(first_image.name))
    print("First Image URL: {} ".format(first_image.url))

else:
    print("Didn't find any images...")

'''
News
If the search response contains news, the first result's name and url
are printed.
'''
if hasattr(web_data.news, 'value'):

    print("\r\nNews Results#{}".format(len(web_data.news.value)))

    first_news = web_data.news.value[0]
    print("First News name: {} ".format(first_news.name))
    print("First News URL: {} ".format(first_news.url))

else:
    print("Didn't find any news...")

'''
If the search response contains videos, the first result's name and url
are printed.
'''
if hasattr(web_data.videos, 'value'):

    print("\r\nVideos Results#{}".format(len(web_data.videos.value)))

    first_video = web_data.videos.value[0]
    print("First Videos name: {} ".format(first_video.name))
    print("First Videos URL: {} ".format(first_video.url))

else:
    print("Didn't find any videos...")

将 SUBSCRIPTION_KEY 替换为有效订阅密钥。
将 YOUR_ENDPOINT 替换为门户中的终结点 URL，并从终结点中删除“bing/v7.0”部分。
运行该程序。例如：python your_program.py。

定义函数并筛选结果

现在你已经第一次调用了必应 Web 搜索 API，让我们看看几个函数。以下部分重点介绍用于优化查询和筛选结果的 SDK 功能。每个函数都可以添加到在上一部分创建的 Python 程序中。

限制必应返回的结果数

此示例使用 count 和 offset 参数限制通过 SDK 的 search 方法返回的结果数。将会输出初始结果的 name 和 url。

将以下代码添加到 Python 项目：

 # Declare the function.
 def web_results_with_count_and_offset(subscription_key):
     client = WebSearchAPI(CognitiveServicesCredentials(subscription_key))

     try:
         '''
         Set the query, offset, and count using the SDK's search method. See:
         https://learn.microsoft.com/python/api/azure-cognitiveservices-search-websearch/azure.cognitiveservices.search.websearch.operations.weboperations?view=azure-python.
         '''
         web_data = client.web.search(query="Best restaurants in Seattle", offset=10, count=20)
         print("\r\nSearching for \"Best restaurants in Seattle\"")

         if web_data.web_pages.value:
             '''
             If web pages are available, print the # of responses, and the first and second
             web pages returned.
             '''
             print("Webpage Results#{}".format(len(web_data.web_pages.value)))

             first_web_page = web_data.web_pages.value[0]
             print("First web page name: {} ".format(first_web_page.name))
             print("First web page URL: {} ".format(first_web_page.url))

         else:
             print("Didn't find any web pages...")

     except Exception as err:
         print("Encountered exception. {}".format(err))

运行该程序。

新闻和新鲜度的筛选器

此示例使用 response_filter 和 freshness 参数筛选通过 SDK 的 search 方法获得的搜索结果。返回的搜索结果仅限必应发现的过去 24 小时的新闻文章和网页。将会输出初始结果的 name 和 url。

将以下代码添加到 Python 项目：

# Declare the function.
def web_search_with_response_filter(subscription_key):
    client = WebSearchAPI(CognitiveServicesCredentials(subscription_key))
    try:
        '''
        Set the query, response_filter, and freshness using the SDK's search method. See:
        https://learn.microsoft.com/python/api/azure-cognitiveservices-search-websearch/azure.cognitiveservices.search.websearch.operations.weboperations?view=azure-python.
        '''
        web_data = client.web.search(query="xbox",
            response_filter=["News"],
            freshness="Day")
        print("\r\nSearching for \"xbox\" with the response filter set to \"News\" and freshness filter set to \"Day\".")

        '''
        If news articles are available, print the # of responses, and the first and second
        articles returned.
        '''
        if web_data.news.value:

            print("# of news results: {}".format(len(web_data.news.value)))

            first_web_page = web_data.news.value[0]
            print("First article name: {} ".format(first_web_page.name))
            print("First article URL: {} ".format(first_web_page.url))

            print("")

            second_web_page = web_data.news.value[1]
            print("\nSecond article name: {} ".format(second_web_page.name))
            print("Second article URL: {} ".format(second_web_page.url))

        else:
            print("Didn't find any news articles...")

    except Exception as err:
        print("Encountered exception. {}".format(err))

# Call the function.
web_search_with_response_filter(subscription_key)

运行该程序。

使用安全搜索、答案计数和提升筛选器

此示例使用 answer_count、promote 和 safe_search 参数筛选通过 SDK 的 search 方法获得的搜索结果。将会显示初始结果的 name 和 url。

将以下代码添加到 Python 项目：

# Declare the function.
def web_search_with_answer_count_promote_and_safe_search(subscription_key):

    client = WebSearchAPI(CognitiveServicesCredentials(subscription_key))

    try:
        '''
        Set the query, answer_count, promote, and safe_search parameters using the SDK's search method. See:
        https://learn.microsoft.com/python/api/azure-cognitiveservices-search-websearch/azure.cognitiveservices.search.websearch.operations.weboperations?view=azure-python.
        '''
        web_data = client.web.search(
            query="Niagara Falls",
            answer_count=2,
            promote=["videos"],
            safe_search=SafeSearch.strict  # or directly "Strict"
        )
        print("\r\nSearching for \"Niagara Falls\"")

        '''
        If results are available, print the # of responses, and the first result returned.
        '''
        if web_data.web_pages.value:

            print("Webpage Results#{}".format(len(web_data.web_pages.value)))

            first_web_page = web_data.web_pages.value[0]
            print("First web page name: {} ".format(first_web_page.name))
            print("First web page URL: {} ".format(first_web_page.url))

        else:
            print("Didn't see any Web data..")

    except Exception as err:
        print("Encountered exception. {}".format(err))

运行该程序。

清理资源

完成本项目以后，请务必从程序代码中删除订阅密钥并停用虚拟环境。

后续步骤

Azure AI 服务 Python SDK 示例

另请参阅

Azure Python SDK 参考

通过

快速入门：使用必应 Web 搜索客户端库

先决条件

创建 Azure 资源

创建项目并安装依赖项

声明依赖项

创建项目基架

构造请求

处理响应

声明 main 方法

运行应用程序

定义函数并筛选结果

限制必应返回的结果数

新闻筛选器

使用安全搜索、答案计数和提升筛选器

清理资源

后续步骤

必备条件

创建 Azure 资源

创建一个项目并设置 POM 文件

声明依赖项

声明 BingWebSearchSample 类

构造请求

处理响应

声明 main 方法

运行程序

清理资源

后续步骤

另请参阅

必备条件

创建 Azure 资源

设置开发环境

创建一个项目并声明必需的模块

对客户端进行实例化

发出请求并输出结果

运行程序

清理资源

后续步骤

另请参阅

先决条件

创建 Azure 资源

创建并配置虚拟环境

Python 2.x

Python 3.x

创建客户端并输出初始结果

定义函数并筛选结果

限制必应返回的结果数

新闻和新鲜度的筛选器

使用安全搜索、答案计数和提升筛选器

清理资源

后续步骤

另请参阅

其他资源