快速入门：使用必应视频搜索 REST API 和 Java 来搜索视频

项目
05/22/2020

警告

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

根据此快速入门中的说明对必应视频搜索 API 进行第一次调用。这个简单的 Java 应用程序会向该 API 发送一个 HTTP 视频搜索查询并显示 JSON 响应。虽然此应用程序是使用 Java 编写的，但 API 是一种 RESTful Web 服务，与大多数编程语言兼容。

GitHub 上提供了此示例的源代码以及更多的错误处理、功能和代码注释。

先决条件

创建 Azure 资源

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

必应搜索 v7 资源

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

多服务资源

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

创建并初始化项目

在你最喜欢的 IDE 或编辑器中新建一个 Java 项目，并导入以下库：

import java.net.*;
import java.util.*;
import java.io.*;
import javax.net.ssl.HttpsURLConnection;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

创建名为的 SearchResults 新类用于存储标头和 API 返回的 JSON 响应。

// Container class for search results encapsulates relevant headers and JSON data
class SearchResults{
    HashMap<String, String> relevantHeaders;
    String jsonResponse;
    SearchResults(HashMap<String, String> headers, String json) {
        relevantHeaders = headers;
        jsonResponse = json;
    }
}

创建名为的 SearchVideos() 新方法，其中包含 API 终结点主机和路径、订阅密钥与搜索词的变量。此方法将返回 SearchResults 对象。对于 host 值，可以使用以下代码中的全局终结点，或者使用资源的 Azure 门户中显示的自定义子域终结点。

public static SearchResults SearchVideos (String searchQuery) throws Exception {
    static String subscriptionKey = "enter your key here";
    static String host = "https://api.cognitive.microsoft.com";
    static String path = "/bing/v7.0/videos/search";
    static String searchTerm = "kittens";
}

构造并发送搜索请求

在 SearchVideos() 方法中，执行以下步骤：

通过组合 API 主机、路径以及已编码的搜索查询来构造请求的 URL。使用 openConnection() 创建连接，然后将订阅密钥添加到 Ocp-Apim-Subscription-Key 标头。

URL url = new URL(host + path + "?q=" +  URLEncoder.encode(searchQuery, "UTF-8"));
HttpsURLConnection connection = (HttpsURLConnection)url.openConnection();
connection.setRequestProperty("Ocp-Apim-Subscription-Key", subscriptionKey);

获取 API 的响应，并存储 JSON 字符串。

InputStream stream = connection.getInputStream();
String response = new Scanner(stream).useDelimiter("\\A").next();

使用 getHeaderFields() 提取响应中的 HTTP 标头，并在 results 对象中存储必应相关的标头。然后关闭流并返回结果。

// extract Bing-related HTTP headers
Map<String, List<String>> headers = connection.getHeaderFields();
for (String header : headers.keySet()) {
    if (header == null) continue;      // may have null key
    if (header.startsWith("BingAPIs-") || header.startsWith("X-MSEdge-")) {
        results.relevantHeaders.put(header, headers.get(header).get(0));
    }
}
stream.close();
return results;

设置响应的格式

创建名为 prettify() 的方法，用于设置必应视频 API 返回的响应的格式。使用 Gson 库的 JsonParser 将 JSON 字符串转换为对象。然后，使用 GsonBuilder() 和 toJson() 创建带格式的字符串。

// pretty-printer for JSON; uses GSON parser to parse and re-serialize
public static String prettify(String json_text) {
    JsonParser parser = new JsonParser();
    JsonObject json = parser.parse(json_text).getAsJsonObject();
    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    return gson.toJson(json);
}

发送请求并列显响应

在应用程序的 main 方法中，结合搜索词调用 SearchVideos。然后，列显响应中存储的 HTTP 标头以及 API 返回的 JSON 字符串。

public static void main (String[] args) {

    SearchResults result = SearchVideos(searchTerm);
    //print the Relevant HTTP Headers
    for (String header : result.relevantHeaders.keySet())
        System.out.println(header + ": " + result.relevantHeaders.get(header));
    System.out.println(prettify(result.jsonResponse));
}

JSON 响应

在 JSON 中返回成功的响应，如以下示例所示：

{
    "_type": "Videos",
    "instrumentation": {},
    "readLink": "https://api.cognitive.microsoft.com/api/v7/videos/search?q=kittens",
    "webSearchUrl": "https://www.bing.com/videos/search?q=kittens",
    "totalEstimatedMatches": 1000,
    "value": [
        {
            "webSearchUrl": "https://www.bing.com/videos/search?q=kittens&view=...",
            "name": "Top 10 cute kitten videos compilation",
            "description": "HELP HOMELESS ANIMALS AND WIN A PRIZE BY CHOOSING...",
            "thumbnailUrl": "https://tse4.mm.bing.net/th?id=OVP.n1aE_Oikl4MtzBb...",
            "datePublished": "2014-11-12T22:47:36.0000000",
            "publisher": [
                {
                    "name": "Fabrikam"
                }
            ],
            "creator": {
                "name": "Marcus Appel"
            },
            "isAccessibleForFree": true,
            "contentUrl": "https://www.fabrikam.com/watch?v=8HVWitAW-Qg",
            "hostPageUrl": "https://www.fabrikam.com/watch?v=8HVWitAW-Qg",
            "encodingFormat": "h264",
            "hostPageDisplayUrl": "https://www.fabrikam.com/watch?v=8HVWitAW-Qg",
            "width": 480,
            "height": 360,
            "duration": "PT3M52S",
            "motionThumbnailUrl": "https://tse4.mm.bing.net/th?id=OM.j4QyJAENJphdZQ_1501386166&pid=Api",
            "embedHtml": "<iframe width=\"1280\" height=\"720\" src=\"https://www.fabrikam.com/embed/8HVWitAW-Qg?autoplay=1\" frameborder=\"0\" allowfullscreen></iframe>",
            "allowHttpsEmbed": true,
            "viewCount": 7513633,
            "thumbnail": {
                "width": 300,
                "height": 168
            },
            "videoId": "655D98260D012432848F6558260D012432848F",
            "allowMobileEmbed": true,
            "isSuperfresh": false
        },
        . . .
    ],
    "nextOffset": 36,
    "queryExpansions": [
        {
            "text": "Kittens Meowing",
            "displayText": "Meowing",
            "webSearchUrl": "https://www.bing.com/videos/search?q=Kittens+Meowing...",
            "searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search...",
            "thumbnail": {
                "thumbnailUrl": "https://tse3.mm.bing.net/th?q=Kittens+Meowing&pid..."
            }
        },
        {
            "text": "Funny Kittens",
            "displayText": "Funny",
            "webSearchUrl": "https://www.bing.com/videos/search?q=Funny+Kittens...",
            "searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search...",
            "thumbnail": {
                "thumbnailUrl": "https://tse3.mm.bing.net/th?q=Funny+Kittens&..."
            }
        },
        . . .
    ],
    "pivotSuggestions": [
        {
            "pivot": "kittens",
            "suggestions": [
                {
                    "text": "Cat",
                    "displayText": "Cat",
                    "webSearchUrl": "https://www.bing.com/videos/search?q=Cat...",
                    "searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search?...",
                    "thumbnail": {
                        "thumbnailUrl": "https://tse3.mm.bing.net/th?q=Cat&pid=Api..."
                    }
                },
                {
                    "text": "Feral Cat",
                    "displayText": "Feral Cat",
                    "webSearchUrl": "https://www.bing.com/videos/search?q=Feral+Cat...",
                    "searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search...",
                    "thumbnail": {
                        "thumbnailUrl": "https://tse3.mm.bing.net/th?q=Feral+Cat&pid=Api&..."
                    }
                }
            ]
        }
    ],
    "relatedSearches": [
        {
            "text": "Kittens Being Born",
            "displayText": "Kittens Being Born",
            "webSearchUrl": "https://www.bing.com/videos/search?q=Kittens+Being+Born...",
            "searchLink": "https://api.cognitive.microsoft.com/api/v7/videos/search?...",
            "thumbnail": {
                "thumbnailUrl": "https://tse1.mm.bing.net/th?q=Kittens+Being+Born&pid=..."
            }
        },
        . . .
    ]
}

后续步骤

构建单页 Web 应用

另请参阅

什么是必应视频搜索 API？