Quickstart: Use the Bing Visual Search Java client library
Use this quickstart to begin getting image insights from the Bing Visual Search service, using the Java client library. While Bing Visual Search has a REST API compatible with most programming languages, the client library provides an easy way to integrate the service into your applications. The source code for this quickstart can be found on GitHub.
Use the Bing Visual Search client library for Java to:
- Upload an image to send a visual search request.
- Get the image insight token and visual search tags.
Reference documentation | Library source code | Artifact (Maven) | Samples
Prerequisites
- Azure subscription - Create one for free.
- The current version of the Java Development Kit (JDK).
- The Gradle build tool, or another dependency manager.
After you get a key from your resource, create an environment variable for the key, named BING_SEARCH_V7_SUBSCRIPTION_KEY.
Create a new Gradle project
In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it.
mkdir myapp && cd myapp
Run the gradle init command from your working directory. This command will create essential build files for Gradle, including build.gradle.kts which is used at runtime to create and configure your application.
gradle init --type basic
When prompted to choose a DSL, select Kotlin.
Locate build.gradle.kts and open it with your preferred IDE or text editor. Then copy in this build configuration:
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")
}
Create a folder for your sample app. From your working directory, run the following command:
mkdir -p src/main/java
Create a folder for the image you want to upload to the API. Place the image inside the resources folder.
mkdir -p src/main/resources
Navigate to the new folder and create a file called BingVisualSearchSample.java. Open it in your preferred editor or IDE and add the following import statements:
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;```
Then create a new class.
```java
public class BingVisualSearchSample {
}
In the application's main method, create variables for your resource's Azure endpoint and key. If you created the environment variable after you launched the application, you will need to close and reopen the editor, IDE, or shell running it to access the variable. Then create a byte[] for the image you'll be uploading. Create a try block for the methods you'll define later, and load the image and convert it to bytes using toByteArray().
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();
}
}
Install the client library
This quickstart uses the Gradle dependency manager. You can find the client library and information for other dependency managers on the Maven Central Repository.
In your project's build.gradle.kts file, be sure to include the client library as an implementation statement.
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")
}
Code examples
These code snippets show you how to do the following tasks with the Bing Visual Search client library and Java:
- Authenticate the client
- Send a visual search request
- Print the image insight token and visual search tags
Authenticate the client
Note
This quickstart assumes you've created an environment variable for your Bing Visual Search key, named BING_SEARCH_V7_SUBSCRIPTION_KEY.
In your main method, be sure to use your subscription key to instantiate a BingVisualSearchAPI object.
BingVisualSearchAPI client = BingVisualSearchManager.authenticate(subscriptionKey);
Send a visual search request
In a new method, send the image byte array (which was created in the main() method) using the client's bingImages().visualSearch() method.
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);
}
Print the image insight token and visual search tags
Check if the ImageKnowledge object is null. If not, print the image insights token, the number of tags, the number of actions, and the first action type.
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!");
}
}
}
Run the application
You can build the app with:
gradle build
Run the application with the run goal:
gradle run