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

Artigo
02/27/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.

Introdução à biblioteca de clientes da Pesquisa Personalizada do Bing para C#. Siga essas etapas para instalar o pacote e testar o código de exemplo para tarefas básicas. A API de Pesquisa Personalizada do Bing permite que você crie experiências de pesquisa personalizada sem anúncios para os tópicos de seu interesse. O código-fonte desta amostra pode ser encontrado no GitHub.

Use a biblioteca de clientes da Pesquisa Personalizada do Bing para C# com as seguintes finalidades:

Localizar os resultados da pesquisa na Web, na sua instância da Pesquisa Personalizada do Bing.

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

Pré-requisitos

Uma instância da Pesquisa Personalizada do Bing. Confira Início Rápido: Criar sua primeira instância da Pesquisa Personalizada do Bing para obter mais informações.
Microsoft .NET Core
Qualquer edição do Visual Studio 2017 ou posterior
Se você estiver usando Linux/MacOS, este aplicativo poderá ser executado usando Mono.
O pacote NuGet Pesquisa Personalizada do Bing.
- No Gerenciador de Soluções do Visual Studio, clique com o botão direito do mouse no seu projeto e selecione Gerenciar Pacotes NuGet no menu. Instale o pacote Microsoft.Azure.CognitiveServices.Search.CustomSearch. A instalação do pacote Pesquisa Personalizada do NuGet também instala os assemblies a seguir:
  - Microsoft.Rest.ClientRuntime
  - Microsoft.Rest.ClientRuntime.Azure
  - Newtonsoft.Json

Criar um recurso do Azure

Comece a usar a API de Pesquisa Personalizada do Bing criando um dos recursos do Azure a seguir.

Recurso de Pesquisa Personalizada do Bing

Disponível por meio do portal do Azure até que você exclua o recurso.
Use o tipo de preço gratuito para experimentar o serviço e atualize mais tarde para uma camada paga para produção.

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 aplicativo de console C#. Depois, adicione os seguintes pacotes ao seu projeto.
```
using System;
using System.Linq;
using Microsoft.Azure.CognitiveServices.Search.CustomSearch;
```
No método principal do aplicativo, crie uma instância do cliente de pesquisa com sua chave de API.
```
var client = new CustomSearchAPI(new ApiKeyServiceClientCredentials("YOUR-SUBSCRIPTION-KEY"));
```

Enviar a solicitação de pesquisa e receber uma resposta

Envie uma consulta de pesquisa usando o método SearchAsync() do cliente e salve a resposta. Substitua a YOUR-CUSTOM-CONFIG-ID pela ID de configuração da instância (encontre a ID no portal da Pesquisa Personalizada do Bing). Este exemplo pesquisa "Xbox".
```
// This will look up a single query (Xbox).
var webData = client.CustomInstance.SearchAsync(query: "Xbox", customConfig: Int32.Parse("YOUR-CUSTOM-CONFIG-ID")).Result;
```

O método SearchAsync() retorna um objeto WebData. Use o objeto para iterar em todas as WebPages encontradas. Esse código encontra o primeiro resultado da página da Web e imprime Name e URL da página da Web.

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

    if (firstWebPagesResult != null)
    {
        Console.WriteLine("Number of 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("Couldn't find web results!");
    }
}
else
{
    Console.WriteLine("Didn't see any Web data..");
}

Próximas etapas

Criar um aplicativo Web de Pesquisa Personalizada

Introdução à biblioteca de clientes da Pesquisa Personalizada do Bing para Java. Siga essas etapas para instalar o pacote e testar o código de exemplo para tarefas básicas. A API de Pesquisa Personalizada do Bing permite que você crie experiências de pesquisa personalizada sem anúncios para os tópicos de seu interesse. O código-fonte dessa amostra pode ser encontrado no GitHub

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

Localizar os resultados da pesquisa na Web, na sua instância da Pesquisa Personalizada do Bing.

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

Pré-requisitos

Assinatura do Azure – crie uma gratuitamente.
A versão atual do JDK (Java Development Kit).
A ferramenta de build Gradle ou outro gerenciador de dependência.
Uma instância da Pesquisa Personalizada do Bing. Confira Início Rápido: Criar sua primeira instância da Pesquisa Personalizada do Bing para obter mais informações.

Criar um recurso do Azure

Comece a usar a API de Pesquisa Personalizada do Bing criando um dos recursos do Azure a seguir.

Recurso de Pesquisa Personalizada do Bing

Disponível por meio do portal do Azure até que você exclua o recurso.
Use o tipo de preço gratuito para experimentar o serviço e atualize mais tarde para uma camada paga para produção.

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 AZURE_BING_CUSTOM_SEARCH_API_KEY.

Criar um novo projeto Gradle

Dica

Se você não estiver usando o Gradle, poderá encontrar os detalhes da biblioteca de clientes e para outros gerenciadores de dependência no Repositório Central do Maven.

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 cria arquivos de build essenciais para o Gradle, incluindo um arquivo build.gradle.kts, que é usado no runtime para configurar seu aplicativo.

gradle init --type basic

Quando solicitado a escolher uma DSL, escolha Kotlin.

Instalar a biblioteca de clientes

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

plugins {
    java
    application
}
application {
    mainClassName = "main.java.BingCustomSearchSample"
}
repositories {
    mavenCentral()
}
dependencies {
    compile("org.slf4j:slf4j-simple:1.7.25")
    compile("com.microsoft.azure.cognitiveservices:azure-cognitiveservices-customsearch:1.0.2")
}

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

mkdir src/main/java

Navegue até a nova pasta e crie um arquivo chamado BingCustomSearchSample.java. Abra-o e adicione as seguintes instruções import:

package main.java;

import com.microsoft.azure.cognitiveservices.search.customsearch.BingCustomSearchAPI;
import com.microsoft.azure.cognitiveservices.search.customsearch.BingCustomSearchManager;
import com.microsoft.azure.cognitiveservices.search.customsearch.models.SearchResponse;
import com.microsoft.azure.cognitiveservices.search.customsearch.models.WebPage;

Crie uma classe denominada BingCustomSearchSample

public class BingCustomSearchSample {
}

Na classe, crie um método main e uma variável para a chave do recurso. Se você tiver criado a variável de ambiente depois de iniciar o aplicativo, feche e reabra o editor, o IDE ou o shell em execução para acessar a variável. Você definirá os métodos mais tarde.

public static void main(String[] args) {
    try {

        // Set the BING_CUSTOM_SEARCH_SUBSCRIPTION_KEY and AZURE_BING_SAMPLES_CUSTOM_CONFIG_ID environment variables, 
        // then reopen your command prompt or IDE. If not, you may get an API key not found exception.
        final String subscriptionKey = System.getenv("BING_CUSTOM_SEARCH_SUBSCRIPTION_KEY");
        // If you do not have a customConfigId, you can also use 1 as your value when setting your environment variable.
        final String customConfigId = System.getenv("AZURE_BING_SAMPLES_CUSTOM_CONFIG_ID");

        BingCustomSearchAPI client = BingCustomSearchManager.authenticate(subscriptionKey);

        runSample(client, customConfigId);
    } catch (Exception e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Modelo de objeto

O cliente da Pesquisa Personalizada do Bing é um objeto BingCustomSearchAPI criado no método authenticate() do objeto BingCustomSearchManager. Você pode enviar uma solicitação de pesquisa usando o método BingCustomInstances.search() do cliente.

A resposta da API é um objeto SearchResponse que contém informações sobre a consulta de pesquisa e os resultados da pesquisa.

Exemplos de código

Esses snippets de códigos mostram como realizar as seguintes tarefas com a biblioteca de clientes da Pesquisa Personalizada do Bing para Java:

Autenticar o cliente
Obter resultados da pesquisa na instância de pesquisa personalizada

Autenticar o cliente

O método principal deve incluir um objeto BingCustomSearchManager que usa a chave e chama seu authenticate().

BingCustomSearchAPI client = BingCustomSearchManager.authenticate(subscriptionKey);

Obter resultados da pesquisa na instância de pesquisa personalizada

Use a função BingCustomInstances.search() do cliente para enviar uma consulta de pesquisa para sua instância personalizada. Defina o withCustomConfig para sua ID de configuração personalizada ou por padrão como 1. Depois de obter uma resposta da API, verifique se foram encontrados resultados da pesquisa. Nesse caso, obtenha o primeiro resultado da pesquisa chamando a função webPages().value().get() da resposta e imprima o nome do resultado e a URL.

public static boolean runSample(BingCustomSearchAPI client, String customConfigId) {
    try {

        // This will search for "Xbox" using Bing Custom Search 
        //and print out name and url for the first web page in the results list

        System.out.println("Searching for Query: \"Xbox\"");
        SearchResponse webData = client.bingCustomInstances().search()
            .withCustomConfig(customConfigId != null ? Long.valueOf(customConfigId) : 0)
            .withQuery("Xbox")
            .withMarket("en-us")
            .execute();

        if (webData != null && webData.webPages() != 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 web results!");
            }
        } else {
            System.out.println("Didn't see any Web data..");
        }

        return true;
    } catch (Exception f) {
        System.out.println(f.getMessage());
        f.printStackTrace();
    }
    return false;
}

Executar o aplicativo

Compile o aplicativo com o seguinte comando no diretório principal do projeto:

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 Pesquisa Personalizada

Introdução à biblioteca de clientes da Pesquisa Personalizada do Bing para Python. Siga essas etapas para instalar o pacote e testar o código de exemplo para tarefas básicas. A API de Pesquisa Personalizada do Bing permite criar experiências de pesquisa personalizadas sem anúncios para tópicos importantes para você. O código-fonte desta amostra pode ser encontrado no GitHub.

Use a biblioteca de clientes da Pesquisa Personalizada do Bing para Python com as seguintes finalidades:

Localizar os resultados da pesquisa na Web, na sua instância da Pesquisa Personalizada do Bing.

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

Pré-requisitos

Uma instância da Pesquisa Personalizada do Bing. Confira Início Rápido: Criar sua primeira instância da Pesquisa Personalizada do Bing para obter mais informações.
Python 2.x ou 3.x
O SDK da Pesquisa Personalizada do Bing para Python

Criar um recurso do Azure

Comece a usar a API de Pesquisa Personalizada do Bing criando um dos recursos do Azure a seguir.

Recurso de Pesquisa Personalizada do Bing

Disponível por meio do portal do Azure até que você exclua o recurso.
Use o tipo de preço gratuito para experimentar o serviço e atualize mais tarde para uma camada paga para produção.

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.

Instalar a biblioteca de clientes do Python

Instale a biblioteca de clientes da Pesquisa Personalizada do Bing com o comando a seguir.

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

Crie um novo aplicativo

Crie um novo arquivo Python em seu IDE ou editor favorito e adicione as importações a seguir.

from azure.cognitiveservices.search.customsearch import CustomSearchClient
from msrest.authentication import CognitiveServicesCredentials

Criar um cliente de pesquisa e enviar uma solicitação

Crie uma variável para a chave de assinatura e o ponto de extremidade.

subscription_key = 'your-subscription-key'
endpoint = 'your-endpoint'

Crie uma instância de CustomSearchClient usando um objeto CognitiveServicesCredentials com a chave da assinatura.
```
client = CustomSearchClient(endpoint=endpoint, credentials=CognitiveServicesCredentials(subscription_key))
```
Envie uma solicitação de pesquisa com client.custom_instance.search(). Acrescente o termo de pesquisa ao parâmetro query e defina custom_config para a sua ID de configuração personalizada para usar a instância de pesquisa. Você pode obter sua ID do portal da Pesquisa Personalizada do Bing, clicando na guia Produção.
```
web_data = client.custom_instance.search(query="xbox", custom_config="your-configuration-id")
```

Exibir os resultados da pesquisa

Se resultados da pesquisa de páginas da Web foram encontrados, obtenha o primeiro deles e imprima seu nome, a URL e o total de páginas da Web encontradas.

if web_data.web_pages.value:
    first_web_result = web_data.web_pages.value[0]
    print("Web Pages result count: {}".format(len(web_data.web_pages.value)))
    print("First Web Page name: {}".format(first_web_result.name))
    print("First Web Page url: {}".format(first_web_result.url))
else:
    print("Didn't see any web data..")

Próximas etapas

Criar um aplicativo Web de Pesquisa Personalizada

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

Pré-requisitos

Criar um recurso do Azure

Recurso de Pesquisa Personalizada do Bing

Recurso de vários serviços

Criar e inicializar o aplicativo

Enviar a solicitação de pesquisa e receber uma resposta

Próximas etapas

Pré-requisitos

Criar um recurso do Azure

Recurso de Pesquisa Personalizada do Bing

Recurso de vários serviços

Criar um novo projeto Gradle

Instalar a biblioteca de clientes

Modelo de objeto

Exemplos de código

Autenticar o cliente

Obter resultados da pesquisa na instância de pesquisa personalizada

Executar o aplicativo

Limpar os recursos

Próximas etapas

Pré-requisitos

Criar um recurso do Azure

Recurso de Pesquisa Personalizada do Bing

Recurso de vários serviços

Instalar a biblioteca de clientes do Python

Crie um novo aplicativo

Criar um cliente de pesquisa e enviar uma solicitação

Exibir os resultados da pesquisa

Próximas etapas

Recursos adicionais