Modifier

Partager via

Quickstart: Use the Bing Custom Search Java client library

  • Article

Get started with the Bing Custom Search client library for Java. Follow these steps to install the package and try out the example code for basic tasks. The Bing Custom Search API enables you to create tailored, ad-free search experiences for topics that you care about. The source code for this sample can be found on GitHub.

Use the Bing Custom Search client library for Java to:

  • Find search results on the web from your Bing Custom Search instance.

Reference documentation | Library source code | Artifact (Maven) | Samples

Prerequisites

After you get a key from your resource, create an environment variable for the key, named AZURE_BING_CUSTOM_SEARCH_API_KEY.

Create a new Gradle project

Tip

If you're not using Gradle, you can find the client library details for other dependency managers on the Maven Central Repository.

In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and then navigate to it.

mkdir myapp && cd myapp

Run the gradle init command from your working directory. This command creates essential build files for Gradle, including a build.gradle.kts file that is used at runtime to configure your application.

gradle init --type basic

When prompted to choose a DSL, select Kotlin.

Install the client library

Locate build.gradle.kts and open it with your preferred IDE or text editor. Next, copy in this build configuration. Be sure to include the client library under 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")
}

Create a folder for your sample app. From your working directory, run the following command:

mkdir src/main/java

Navigate to the new folder and create a file called BingCustomSearchSample.java. Open it and add the following import statements:

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;

Create a class named BingCustomSearchSample

public class BingCustomSearchSample {
}

In the class, create a main method and a variable for your resource's key. If you created the environment variable after you launched the application, close and reopen the editor, IDE, or shell running it to access the variable. You will define the methods later.

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

Object model

The Bing Custom Search client is a BingCustomSearchAPI object that's created from the BingCustomSearchManager object's authenticate() method. You can send a search request using the client's BingCustomInstances.search() method.

The API response is a SearchResponse object containing information on the search query, and search results.

Code examples

These code snippets show you how to do the following tasks with the Bing Custom Search client library for Java:

Authenticate the client

Your main method should include a BingCustomSearchManager object that takes your key, and calls its authenticate().

BingCustomSearchAPI client = BingCustomSearchManager.authenticate(subscriptionKey);

Get search results from your custom search instance

Use the client's BingCustomInstances.search() function to send a search query to your custom instance. Set the withCustomConfig to your custom configuration ID, or default to 1. After getting a response from the API, check if any search results were found. If so, get the first search result by calling the response's webPages().value().get() function and print the result's name, and 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;
    }

Run the application

Build the app with the following command from your project's main directory:

gradle build

Run the application with the run goal:

gradle run

Next steps

Build a Custom Search web app