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

在删除资源前，可通过 Azure 门户使用。
选择 S9 定价层。

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

创建并初始化应用程序

在 Visual Studio 中，创建新的项目。然后，添加以下指令。

using Microsoft.Azure.CognitiveServices.Search.VisualSearch;
using Microsoft.Azure.CognitiveServices.Search.VisualSearch.Models;

使用订阅密钥实例化客户端。

var client = new VisualSearchClient(new ApiKeyServiceClientCredentials("YOUR-ACCESS-KEY"));

发送搜索请求

为图像创建 FileStream（在本例中为 TestImages/image.jpg）。然后，使用 client.Images.VisualSearchMethodAsync() 通过客户端发送搜索请求。

 System.IO.FileStream stream = new FileStream(Path.Combine("TestImages", "image.jpg"), FileMode.Open);
 // The knowledgeRequest parameter is not required if an image binary is passed in the request body
 var visualSearchResults = client.Images.VisualSearchMethodAsync(image: stream, knowledgeRequest: (string)null).Result;

分析以前的查询的结果：

// Visual Search results
if (visualSearchResults.Image?.ImageInsightsToken != null)
{
    Console.WriteLine($"Uploaded image insights token: {visualSearchResults.Image.ImageInsightsToken}");
}
else
{
    Console.WriteLine("Couldn't find image insights token!");
}

// List of tags
if (visualSearchResults.Tags.Count > 0)
{
    var firstTagResult = visualSearchResults.Tags[0];
    Console.WriteLine($"Visual search tag count: {visualSearchResults.Tags.Count}");

    // List of actions in first tag
    if (firstTagResult.Actions.Count > 0)
    {
        var firstActionResult = firstTagResult.Actions[0];
        Console.WriteLine($"First tag action count: {firstTagResult.Actions.Count}");
        Console.WriteLine($"First tag action type: {firstActionResult.ActionType}");
    }
    else
    {
        Console.WriteLine("Couldn't find tag actions!");
    }
}

后续步骤

按照本快速入门，开始使用 Java 客户端库通过必应视觉搜索服务获取图像见解。虽然必应视觉搜索具有与大多数编程语言兼容的 REST API，但该客户端库提供了一种简单方法来将服务集成到应用程序中。可以在 GitHub 上找到此快速入门的源代码。

使用适用于 Java 的必应视觉搜索客户端库，可以执行以下操作：

上传图像以发送视觉搜索请求。
获取图像见解标记和视觉搜索标记。

参考文档 | 库源代码 | 项目 (Maven) | 示例

先决条件

Azure 订阅 - 免费创建订阅
最新版本的 Java 开发工具包 (JDK)
Gradle 生成工具，或其他依赖项管理器

创建 Azure 资源

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

在删除资源前，可通过 Azure 门户使用。
选择 S9 定价层。

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

从资源获取密钥后，为密钥创建一个环境变量（名为 BING_SEARCH_V7_SUBSCRIPTION_KEY）。

创建新的 Gradle 项目

在控制台窗口（例如 cmd、PowerShell 或 Bash）中，为应用创建一个新目录并导航到该目录。

mkdir myapp && cd myapp

从工作目录运行 gradle init 命令。此命令将创建 Gradle 的基本生成文件，包括 build.gradle.kts，在运行时将使用该文件创建并配置应用程序。

gradle init --type basic

当提示你选择一个 DSL 时，选择 Kotlin。

找到 build.gradle.kts，并使用喜好的 IDE 或文本编辑器将其打开。然后将以下生成配置复制到其中：

plugins {
    java
    application
}
application {
    mainClassName = "main.java.BingVisualSearchSample"
}
repositories {
    mavenCentral()
}
dependencies {
    compile("org.slf4j:slf4j-simple:1.7.25")
    compile("com.microsoft.azure.cognitiveservices:azure-cognitiveservices-visualsearch:1.0.2-beta")
    compile("com.google.code.gson:gson:2.8.5")
}

为示例应用创建一个文件夹。在工作目录中运行以下命令：

mkdir -p src/main/java

为要上传到 API 的图像创建一个文件夹。将图像放入 resources 文件夹。

mkdir -p src/main/resources

导航到新文件夹，创建名为 BingVisualSearchSample.java 的文件。在喜好的编辑器或 IDE 中打开该文件并添加以下 import 语句：

package main.java;

import com.google.common.io.ByteStreams;
import com.google.gson.Gson;
import com.microsoft.azure.cognitiveservices.search.visualsearch.BingVisualSearchAPI;
import com.microsoft.azure.cognitiveservices.search.visualsearch.BingVisualSearchManager;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.CropArea;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.ErrorResponseException;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.Filters;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.ImageInfo;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.ImageKnowledge;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.ImageTag;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.KnowledgeRequest;
import com.microsoft.azure.cognitiveservices.search.visualsearch.models.VisualSearchRequest;

然后创建一个新类。

public class BingVisualSearchSample {
}

在应用程序的 main 方法中，为该资源的 Azure 终结点和密钥创建变量。如果在启动应用程序后创建了环境变量，则需要关闭再重新打开运行该应用程序的编辑器、IDE 或 shell 才能访问该变量。然后为要上传的图像创建 byte[]。为稍后要定义的方法创建 try 块，加载该图像并使用 toByteArray() 将其转换为字节。

// IMPORTANT: MAKE SURE TO USE S9 PRICING TIER OF THE BING SEARCH V7 API KEY FOR VISUAL SEARCH.
// Otherwise, you will get an invalid subscription key error.
public static void main(String[] args) {

    // Set the BING_SEARCH_V7_SUBSCRIPTION_KEY environment variable with your subscription key,
    // then reopen your command prompt or IDE. If not, you may get an API key not found exception.
    final String subscriptionKey = System.getenv("BING_SEARCH_V7_SUBSCRIPTION_KEY");

    BingVisualSearchAPI client = BingVisualSearchManager.authenticate(subscriptionKey);

    //runSample(client);
    byte[] imageBytes;

    try {
        imageBytes = ByteStreams.toByteArray(ClassLoader.getSystemClassLoader().getResourceAsStream("image.jpg"));
        visualSearch(client, imageBytes);
        searchWithCropArea(client, imageBytes);
        // wait 1 second to avoid rate limiting
        Thread.sleep(1000);
        searchWithFilter(client);
        searchUsingCropArea(client);
        searchUsingInsightToken(client);
    }
    catch (java.io.IOException f) {
        System.out.println(f.getMessage());
        f.printStackTrace();
    }
    catch (java.lang.InterruptedException f){
        f.printStackTrace();
    }

}

安装客户端库

本快速入门使用 Gradle 依赖项管理器。可以在 Maven 中央存储库中找到客户端库以及其他依赖项管理器的信息。

在项目的 build.gradle.kts 文件中，请务必以 implementation 语句的形式包含客户端库。

dependencies {
    compile("org.slf4j:slf4j-simple:1.7.25")
    compile("com.microsoft.azure.cognitiveservices:azure-cognitiveservices-visualsearch:1.0.2-beta")
    compile("com.google.code.gson:gson:2.8.5")
}

代码示例

这些代码片段演示如何使用必应视觉搜索客户端库和 Java 执行以下任务：

对客户端进行身份验证
发送视觉搜索请求
输出图像见解标记和视觉搜索标记

验证客户端

注意

本快速入门假设你已为必应视觉搜索密钥创建了名为 BING_SEARCH_V7_SUBSCRIPTION_KEY 的环境变量。

在 main 方法中，请务必使用订阅密钥实例化 BingVisualSearchAPI 对象。

BingVisualSearchAPI client = BingVisualSearchManager.authenticate(subscriptionKey);

发送视觉搜索请求

在新方法中，使用客户端的 bingImages().visualSearch() 方法发送图像字节数组（在 main() 方法中创建）。

public static void visualSearch(BingVisualSearchAPI client, byte[] imageBytes){
    System.out.println("Calling Bing Visual Search with image binary");
    ImageKnowledge visualSearchResults = client.bingImages().visualSearch()
            .withImage(imageBytes)
            .execute();
    PrintVisualSearchResults(visualSearchResults);

}

输出图像见解标记和视觉搜索标记

检查 ImageKnowledge 对象是否为 null。如果不是，则输出图像见解标记、标记数量、操作数量和第一个操作类型。

static void PrintVisualSearchResults(ImageKnowledge visualSearchResults) {
    if (visualSearchResults == null) {
        System.out.println("No visual search result data.");
    } else {
        // Print token

        if (visualSearchResults.image() != null && visualSearchResults.image().imageInsightsToken() != null) {
            System.out.println("Found uploaded image insights token: " + visualSearchResults.image().imageInsightsToken());
        } else {
            System.out.println("Couldn't find image insights token!");
        }

        // List tags

        if (visualSearchResults.tags() != null && visualSearchResults.tags().size() > 0) {
            System.out.format("Found visual search tag count: %d\n", visualSearchResults.tags().size());
            ImageTag firstTagResult = visualSearchResults.tags().get(0);

            // List of actions in first tag

            if (firstTagResult.actions() != null && firstTagResult.actions().size() > 0) {
                System.out.format("Found first tag action count: %d\n", firstTagResult.actions().size());
                System.out.println("Found first tag action type: " + firstTagResult.actions().get(0).actionType());
            }
        } else {
            System.out.println("Couldn't find image tags!");
        }
    }
}

运行应用程序

可使用以下命令生成应用：

gradle build

使用 run 目标运行应用程序：

gradle run

清理资源

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

后续步骤

按照本快速入门，开始使用 JavaScript 客户端库通过必应视觉搜索服务获取图像见解。虽然必应视觉搜索具有与大多数编程语言兼容的 REST API，但该客户端库提供了一种简单方法来将服务集成到应用程序中。可以在 GitHub 上找到此示例的源代码。

参考文档 | | 包 (NPM) | 示例

先决条件

最新版本的 Node.js。
适用于 JavaScript 的必应视觉搜索 SDK
- 若要安装，请运行 npm install @azure/cognitiveservices-visualsearch
@azure/ms-rest-azure-js 包中的 CognitiveServicesCredentials 类，用于对客户端进行身份验证。
- 若要安装，请运行 npm install @azure/ms-rest-azure-js

创建 Azure 资源

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

在删除资源前，可通过 Azure 门户使用。
选择 S9 定价层。

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

创建并初始化应用程序

在你喜欢使用的 IDE 或编辑器中创建新的 JavaScript 文件，然后添加以下要求。针对订阅密钥、自定义配置 ID 和要上传的图像的文件路径创建变量。

const os = require("os");
const async = require('async');
const fs = require('fs');
const Search = require('@azure/cognitiveservices-visualsearch');
const CognitiveServicesCredentials = require('@azure/ms-rest-azure-js').CognitiveServicesCredentials;

let keyVar = 'YOUR-VISUAL-SEARCH-ACCESS-KEY';
let credentials = new CognitiveServicesCredentials(keyVar);
let filePath = "../Data/image.jpg";

对客户端进行实例化。

let visualSearchClient = new Search.VisualSearchClient(credentials);

搜索图像

使用 fs.createReadStream() 读取图像文件，并针对搜索请求和结果创建变量。然后使用客户端搜索图像。

let fileStream = fs.createReadStream(filePath);
let visualSearchRequest = JSON.stringify({});
let visualSearchResults;
try {
    visualSearchResults = await visualSearchClient.images.visualSearch({
        image: fileStream,
        knowledgeRequest: visualSearchRequest
    });
    console.log("Search visual search request with binary of image");
} catch (err) {
    console.log("Encountered exception. " + err.message);
}

分析以前的查询的结果：

// Visual Search results
if (visualSearchResults.image.imageInsightsToken) {
    console.log(`Uploaded image insights token: ${visualSearchResults.image.imageInsightsToken}`);
}
else {
    console.log("Couldn't find image insights token!");
}

// List of tags
if (visualSearchResults.tags.length > 0) {
    let firstTagResult = visualSearchResults.tags[0];
    console.log(`Visual search tag count: ${visualSearchResults.tags.length}`);

    // List of actions in first tag
    if (firstTagResult.actions.length > 0) {
        let firstActionResult = firstTagResult.actions[0];
        console.log(`First tag action count: ${firstTagResult.actions.length}`);
        console.log(`First tag action type: ${firstActionResult.actionType}`);
    }
    else {
        console.log("Couldn't find tag actions!");
    }

}
else {
    console.log("Couldn't find image tags!");
}

后续步骤

按照本快速入门，开始使用 Python 客户端库通过必应视觉搜索服务获取图像见解。虽然必应视觉搜索具有与大多数编程语言兼容的 REST API，但该客户端库提供了一种简单方法来将服务集成到应用程序中。可以在 GitHub 上找到此示例的源代码

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

先决条件

Python 2.x 或 3.x
建议使用虚拟环境。使用 venv 模块安装并初始化虚拟环境。
适用于 Python 的必应视觉搜索客户端库。通过使用以下命令来安装它：
1. cd mytestenv
2. python -m pip install azure-cognitiveservices-search-visualsearch

创建 Azure 资源

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

在删除资源前，可通过 Azure 门户使用。
选择 S9 定价层。

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

创建并初始化应用程序

在你喜欢使用的 IDE 或编辑器中创建新的 Python 文件，然后添加以下 import 语句。

import http.client, urllib.parse
import json
import os.path
from azure.cognitiveservices.search.visualsearch import VisualSearchClient
from azure.cognitiveservices.search.visualsearch.models import (
    VisualSearchRequest,
    CropArea,
    ImageInfo,
    Filters,
    KnowledgeRequest,
)
from msrest.authentication import CognitiveServicesCredentials

针对订阅密钥、自定义配置 ID 和要上传的图像创建变量。

subscription_key = 'YOUR-VISUAL-SEARCH-ACCESS-KEY'
PATH = 'C:\\Users\\USER\\azure-cognitive-samples\\mytestenv\\TestImages\\'
image_path = os.path.join(PATH, "image.jpg")

对客户端进行实例化

client = VisualSearchClient(endpoint="https://api.cognitive.microsoft.com", credentials=CognitiveServicesCredentials(subscription_key))

发送搜索请求

打开图像文件，将 VisualSearchRequest() 串行化，并将其传递为 visual_search() 的 knowledge_request 参数。

with open(image_path, "rb") as image_fd:
    # You need to pass the serialized form of the model
    knowledge_request = json.dumps(VisualSearchRequest().serialize())

    print("\r\nSearch visual search request with binary of dog image")
    result = client.images.visual_search(image=image_fd, knowledge_request=knowledge_request)

如果返回了任何结果，则打印它们和标记以及第一个标记中的操作。

if not result:
        print("No visual search result data.")

        # Visual Search results
    if result.image.image_insights_token:
        print("Uploaded image insights token: {}".format(result.image.image_insights_token))
    else:
        print("Couldn't find image insights token!")

    # List of tags
    if result.tags:
        first_tag = result.tags[0]
        print("Visual search tag count: {}".format(len(result.tags)))

        # List of actions in first tag
        if first_tag.actions:
            first_tag_action = first_tag.actions[0]
            print("First tag action count: {}".format(len(first_tag.actions)))
            print("First tag action type: {}".format(first_tag_action.action_type))
        else:
            print("Couldn't find tag actions!")
    else:
        print("Couldn't find image tags!")

后续步骤