Início Rápido: Usar a biblioteca de clientes da Pesquisa Visual do Bing

Artigo
03/26/2020

Aviso

Em 30 de outubro de 2020, as APIs de Pesquisa do Bing foram migradas dos serviços de IA do Azure para os Serviços de Pesquisa do Bing. Esta documentação é fornecida apenas para referência. Para obter a documentação atualizada, consulte a documentação da API de pesquisa do Bing. Para obter instruções sobre como criar novos recursos do Azure para a Pesquisa do Bing, consulte Criar um recurso de Pesquisa do Bing por meio do Azure Marketplace.

Use este início rápido para começar a obter insights de imagens do serviço de Pesquisa Visual do Bing, usando a biblioteca de clientes C#. Embora a Pesquisa Visual do Bing tenha uma API REST compatível com a maioria das linguagens de programação, a biblioteca de clientes oferece uma forma fácil de integrar o serviço aos seus aplicativos. O código-fonte desta amostra pode ser encontrado no GitHub.

Documentação de referência | Código-fonte da biblioteca | Pacote (NuGet) | Exemplos

Pré-requisitos

Visual Studio 2019.
Se você estiver usando Linux/MacOS, este aplicativo poderá ser executado usando Mono.
O pacote de Pesquisa Visual do NuGet.
- No Gerenciador de Soluções no Visual Studio, clique com o botão direito do mouse no seu projeto e selecione Manage NuGet Packages no menu. Instale o pacote Microsoft.Azure.CognitiveServices.Search.VisualSearch. Instalar os pacotes do NuGet também instala o seguinte:
  - Microsoft.Rest.ClientRuntime
  - Microsoft.Rest.ClientRuntime.Azure
  - Newtonsoft.Json

Criar um recurso do Azure

Comece a usar a API da Pesquisa Visual do Bing criando um dos seguintes recursos do Azure:

Recurso de Pesquisa do Bing v7

Disponível por meio do portal do Azure até que você exclua o recurso.
Selecione o tipo de preço S9.

Recurso de vários serviços

Disponível por meio do portal do Azure até que você exclua o recurso.
Use a mesma chave e ponto de extremidade para seus aplicativos nos vários serviços de IA do Azure.

Criar e inicializar o aplicativo

No Visual Studio, crie um novo projeto. Em seguida, adicione as seguintes diretivas.

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

Crie uma instância do cliente com sua chave de assinatura.

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

Enviar uma solicitação de pesquisa

Criar uma FileStream para suas imagens (neste caso, TestImages/image.jpg). Em seguida, use o cliente para enviar uma solicitação de pesquisa usando 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;

Analise os resultados das consultas anteriores:

// 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!");
    }
}

Próximas etapas

Criar um aplicativo Web de página única

Use este início rápido para começar a obter insights de imagens do serviço de Pesquisa Visual do Bing, usando a biblioteca de clientes Java. Embora a Pesquisa Visual do Bing tenha uma API REST compatível com a maioria das linguagens de programação, a biblioteca de clientes oferece uma forma fácil de integrar o serviço aos seus aplicativos. O código-fonte deste Início Rápido pode ser encontrado no GitHub.

Use a biblioteca de clientes da Pesquisa Visual do Bing para Java para:

Fazer upload de uma imagem para enviar uma solicitação de pesquisa visual.
Obter o token do insight da imagem e as marcas da pesquisa visual.

Documentação de referência | Código-fonte da biblioteca | Artefato (Maven) | Exemplos

Pré-requisitos

Assinatura do Azure – Criar uma gratuitamente
A versão atual do JDK (Java Development Kit)
A ferramenta de build do Gradle ou outro gerenciador de dependência

Criar um recurso do Azure

Comece a usar a API da Pesquisa Visual do Bing criando um dos seguintes recursos do Azure:

Recurso de Pesquisa do Bing v7

Disponível por meio do portal do Azure até que você exclua o recurso.
Selecione o tipo de preço S9.

Recurso de vários serviços

Disponível por meio do portal do Azure até que você exclua o recurso.
Use a mesma chave e ponto de extremidade para seus aplicativos nos vários serviços de IA do Azure.

Depois de obter uma chave do recurso, crie uma variável de ambiente para a chave, chamada BING_SEARCH_V7_SUBSCRIPTION_KEY.

Criar um novo projeto Gradle

Em uma janela de console (como cmd, PowerShell ou Bash), crie um novo diretório para seu aplicativo e navegue até ele.

mkdir myapp && cd myapp

Execute o comando gradle init em seu diretório de trabalho. Esse comando criará arquivos de build essenciais para o Gradle, incluindo build.gradle.kts, que é usado em runtime para criar e configurar seu aplicativo.

gradle init --type basic

Quando solicitado a escolher uma DSL, escolha Kotlin.

Localize o build.gradle.kts e abra-o com seu IDE ou editor de texto preferencial. Depois copie nessa configuração de build:

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")
}

Crie uma pasta para seu aplicativo de exemplo. Do diretório de trabalho, execute o seguinte comando:

mkdir -p src/main/java

Crie uma pasta para a imagem da qual deseja fazer upload na API. Coloque a imagem dentro da pasta resources.

mkdir -p src/main/resources

Navegue até a nova pasta e crie um arquivo chamado BingVisualSearchSample.java. Abra-a no editor ou IDE de sua preferência e adicione as seguintes instruções 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;

Em seguida, crie uma classe.

public class BingVisualSearchSample {
}

No método main do aplicativo, crie variáveis para a chave e o ponto de extremidade do Azure do recurso. Se você criou a variável de ambiente depois de iniciar o aplicativo, será necessário fechar e recarregar o editor, o IDE ou o shell em execução para acessar a variável. Em seguida, crie um byte[] para a imagem que você carregará. Crie um bloco try para os métodos que você definirá posteriormente, carregue a imagem e converta-a em bytes usando 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();
    }

}

Instalar a biblioteca de clientes

Este início rápido usa o gerenciador de dependência do Gradle. Você pode encontrar a biblioteca de clientes e informações para outros gerenciadores de dependência no Repositório Central do Maven.

No arquivo build.gradle.kts do projeto, lembre-se de incluir a biblioteca de clientes como uma instrução 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")
}

Exemplos de código

Esses snippets de código mostram como realizar as seguintes tarefas com a biblioteca de clientes da Pesquisa Visual do Bing e o Java:

Autenticar o cliente
Enviar uma solicitação de pesquisa visual
Imprimir o token do insight da imagem e as marcas da pesquisa visual

Autenticar o cliente

Observação

Este início rápido pressupõe que você tenha criado uma variável de ambiente para a chave da Pesquisa Visual do Bing, chamada BING_SEARCH_V7_SUBSCRIPTION_KEY.

No método principal, lembre-se de usar sua chave de assinatura para criar uma instância de um objeto BingVisualSearchAPI.

BingVisualSearchAPI client = BingVisualSearchManager.authenticate(subscriptionKey);

Enviar uma solicitação de pesquisa visual

Em um novo método, envie a matriz de bytes da imagem (que foi criada no método main()) usando o método bingImages().visualSearch() do cliente.

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);

}

Imprimir o token do insight da imagem e as marcas da pesquisa visual

Verifique se o objeto ImageKnowledge é nulo. Se ele não for, imprima o token de insights da imagem, o número de marcas, o número de ações e o primeiro tipo de ação.

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!");
        }
    }
}

Executar o aplicativo

É possível criar o aplicativo com:

gradle build

Execute o aplicativo com a meta run:

gradle run

Limpar os recursos

Se quiser limpar e remover uma assinatura dos serviços de IA do Azure, você poderá excluir o recurso ou grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Próximas etapas

Criar um aplicativo Web de página única

Use este início rápido para começar a obter insights de imagens do serviço de Pesquisa Visual do Bing, usando a biblioteca de clientes JavaScript. Embora a Pesquisa Visual do Bing tenha uma API REST compatível com a maioria das linguagens de programação, a biblioteca de clientes oferece uma forma fácil de integrar o serviço aos seus aplicativos. O código-fonte desta amostra pode ser encontrado no GitHub.

Documentação de referência | | Pacote (NPM) | Amostras

Pré-requisitos

A versão mais recente do Node.js.
O SDK da Pesquisa Visual do Bing para JavaScript
- Para instalar, execute npm install @azure/cognitiveservices-visualsearch
A classe CognitiveServicesCredentials do pacote @azure/ms-rest-azure-js para autenticar o cliente.
- Para instalar, execute npm install @azure/ms-rest-azure-js

Criar um recurso do Azure

Comece a usar a API da Pesquisa Visual do Bing criando um dos seguintes recursos do Azure:

Recurso de Pesquisa do Bing v7

Disponível por meio do portal do Azure até que você exclua o recurso.
Selecione o tipo de preço S9.

Recurso de vários serviços

Disponível por meio do portal do Azure até que você exclua o recurso.
Use a mesma chave e ponto de extremidade para seus aplicativos nos vários serviços de IA do Azure.

Criar e inicializar o aplicativo

Crie um novo arquivo JavaScript em seu IDE ou editor favorito e adicione os seguintes requisitos. Em seguida, crie variáveis para sua chave de assinatura, uma ID de configuração personalizada e o caminho do arquivo para a imagem que você deseja carregar.

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";

Instancie o cliente.

let visualSearchClient = new Search.VisualSearchClient(credentials);

Pesquisar imagens

Use fs.createReadStream() para ler em seu arquivo de imagem e crie variáveis para sua solicitação de pesquisa e resultados. Em seguida, use o cliente para pesquisar imagens.

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);
}

Analise os resultados das consultas anteriores:

// 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!");
}

Próximas etapas

Criar um aplicativo Web de página única

Use este início rápido para começar a obter insights de imagens do serviço da Pesquisa Visual do Bing, usando a biblioteca de clientes Python. Embora a Pesquisa Visual do Bing tenha uma API REST compatível com a maioria das linguagens de programação, a biblioteca de clientes oferece uma forma fácil de integrar o serviço aos seus aplicativos. O código-fonte dessa amostra pode ser encontrado no GitHub

Documentação de referência | Código-fonte da biblioteca | Pacote (PyPi) | Amostras

Pré-requisitos

Python 2.x ou 3.x
É recomendável usar um ambiente virtual. Instale e inicialize o ambiente virtual com o módulo venv.
A biblioteca de clientes da Pesquisa Visual do Bing para Python. É possível instalá-lo com os seguintes comandos:
1. cd mytestenv
2. python -m pip install azure-cognitiveservices-search-visualsearch

Criar um recurso do Azure

Comece a usar a API da Pesquisa Visual do Bing criando um dos seguintes recursos do Azure:

Recurso de Pesquisa do Bing v7

Disponível por meio do portal do Azure até que você exclua o recurso.
Selecione o tipo de preço S9.

Recurso de vários serviços

Disponível por meio do portal do Azure até que você exclua o recurso.
Use a mesma chave e ponto de extremidade para seus aplicativos nos vários serviços de IA do Azure.

Criar e inicializar o aplicativo

Crie um novo arquivo Python em seu IDE ou o editor favorito e adicione as seguintes instruções de importação.

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

Crie variáveis para sua chave de assinatura, uma ID de Configuração Personalizada e a imagem que você deseja carregar.

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

Instancie o cliente

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

Enviar a solicitação de pesquisa

Com a imagem do arquivo aberto, serialize VisualSearchRequest() e passe-o como o parâmetro knowledge_request do visual_search().

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)

Se todos os resultados foram retornados, imprima-os, as marcas e as ações na primeira marca.

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!")

Próximas etapas

Criar um aplicativo Web de página única

Início Rápido: Usar a biblioteca de clientes da Pesquisa Visual do Bing

Pré-requisitos

Criar um recurso do Azure

Criar e inicializar o aplicativo

Enviar uma solicitação de pesquisa

Próximas etapas

Pré-requisitos

Criar um recurso do Azure

Criar um novo projeto Gradle

Instalar a biblioteca de clientes

Exemplos de código

Autenticar o cliente

Enviar uma solicitação de pesquisa visual

Imprimir o token do insight da imagem e as marcas da pesquisa visual

Executar o aplicativo

Limpar os recursos

Próximas etapas

Pré-requisitos

Criar um recurso do Azure

Criar e inicializar o aplicativo

Pesquisar imagens

Próximas etapas

Pré-requisitos

Criar um recurso do Azure

Criar e inicializar o aplicativo

Enviar a solicitação de pesquisa

Próximas etapas

Recursos adicionais