Démarrage rapide : Utiliser la bibliothèque de client Recherche visuelle Bing

Avertissement

Le 30 octobre 2020, les API de recherche Bing sont passées des services Azure AI aux services de recherche Bing. Cette documentation est fournie à des fins de référence uniquement. Pour accéder à la documentation mise à jour, consultez la documentation de l’API Recherche Bing. Pour obtenir des instructions sur la création de nouvelles ressources Azure pour Recherche Bing, consultez Créer une ressource Recherche Bing à l’aide de Place de marché Azure.

Utilisez ce guide de démarrage rapide pour commencer à obtenir des insights sur les images à partir du service Recherche visuelle Bing, en utilisant la bibliothèque de client C#. Si l’outil Recherche visuelle Bing dispose d’une API REST compatible avec la plupart des langages de programmation, la bibliothèque de client offre quant à elle un moyen simple d’intégrer le service à vos applications. Le code source de cet exemple est disponible sur GitHub.

Documentation de référence | Code source de la bibliothèque | Package (NuGet) | Exemples

Prérequis

  • Visual Studio 2019.
  • Si vous utilisez Linux/MacOS, cette application peut être exécutée à l’aide de Mono.
  • Package Recherche visuelle NuGet.
    • Dans l’Explorateur de solutions de Visual Studio, cliquez avec le bouton droit sur votre projet et sélectionnez Manage NuGet Packages dans le menu. Installez le package Microsoft.Azure.CognitiveServices.Search.VisualSearch. L’installation des packages NuGet installe également les éléments suivants :
      • Microsoft.Rest.ClientRuntime
      • Microsoft.Rest.ClientRuntime.Azure
      • Newtonsoft.Json

Créer une ressource Azure

Commencez à utiliser l’API Recherche visuelle Bing en créant une des ressources Azure suivantes :

Ressource Recherche Bing v7

  • Disponible via le portail Azure jusqu’à ce que vous supprimiez la ressource.
  • Sélectionnez le niveau tarifaire S9.

Ressource multiservice

  • Disponible via le portail Azure jusqu’à ce que vous supprimiez la ressource.
  • Utilisez la même clé et le même point de terminaison pour vos applications, sur plusieurs services Azure AI.

Créer et initialiser l’application

  1. Dans Visual Studio, créez un projet. Ensuite, ajoutez les directives suivantes.

    using Microsoft.Azure.CognitiveServices.Search.VisualSearch;
    using Microsoft.Azure.CognitiveServices.Search.VisualSearch.Models;
    
  2. Instanciez le client avec votre clé d’abonnement.

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

Envoyer une demande de recherche

  1. Créez un FileStream pour vos images (dans ce cas TestImages/image.jpg). Ensuite, utilisez le client pour envoyer une demande de recherche à l’aide de 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;
    
  2. Analysez les résultats de la requête précédente :

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

Étapes suivantes

Utilisez ce guide de démarrage rapide pour commencer à obtenir des insights sur les images à partir du service Recherche visuelle Bing, en utilisant la bibliothèque de client Java. Si l’outil Recherche visuelle Bing dispose d’une API REST compatible avec la plupart des langages de programmation, la bibliothèque de client offre quant à elle un moyen simple d’intégrer le service à vos applications. Le code source de ce guide de démarrage rapide est disponible sur GitHub.

Utilisez la bibliothèque de client Recherche visuelle Bing pour Java pour :

  • Télécharger une image pour envoyer une demande de recherche visuelle.
  • Obtenir le jeton insights de l’image et les balises de recherche visuelle.

Documentation de référence | Code source de la bibliothèque | Artefact (Maven) | Exemples

Prérequis

Créer une ressource Azure

Commencez à utiliser l’API Recherche visuelle Bing en créant une des ressources Azure suivantes :

Ressource Recherche Bing v7

  • Disponible via le portail Azure jusqu’à ce que vous supprimiez la ressource.
  • Sélectionnez le niveau tarifaire S9.

Ressource multiservice

  • Disponible via le portail Azure jusqu’à ce que vous supprimiez la ressource.
  • Utilisez la même clé et le même point de terminaison pour vos applications, sur plusieurs services Azure AI.

Après avoir obtenu une clé à partir de votre ressource, créez une variable d’environnement pour la clé, nommée BING_SEARCH_V7_SUBSCRIPTION_KEY.

Créer un projet Gradle

Dans une fenêtre de console (telle que cmd, PowerShell ou bash), créez un répertoire pour votre application et accédez-y.

mkdir myapp && cd myapp

Exécutez la commande gradle init à partir de votre répertoire de travail. Cette commande crée des fichiers de build essentiels pour Gradle, notamment build.gradle.kts, qui est utilisé au moment de l’exécution pour créer et configurer votre application.

gradle init --type basic

Quand vous êtes invité à choisir un DSL, sélectionnez Kotlin.

Recherchez build.gradle.kts et ouvrez-le avec votre IDE ou votre éditeur de texte habituel. Copiez-y ensuite cette configuration 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")
}

Créez un dossier pour votre exemple d’application. Entrez la commande suivante à partir de votre répertoire de travail :

mkdir -p src/main/java

Créez un dossier pour l’image à charger sur l’API. Placez l’image dans le dossier resources.

mkdir -p src/main/resources

Accédez au nouveau dossier et créez un fichier nommé BingVisualSearchSample.java. Ouvrez-le dans votre éditeur ou IDE habituel et ajoutez les instructions import suivantes :

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;

Ensuite, créez une classe.

public class BingVisualSearchSample {
}

Dans la méthode main de l’application, créez des variables pour le point de terminaison et la clé Azure de votre ressource. Si vous avez créé la variable d’environnement après avoir lancé l’application, vous devez fermer et rouvrir l’éditeur, l’IDE ou le shell qui l’exécute pour accéder à la variable. Créez ensuite un byte[] pour l’image que vous allez charger. Créez un bloc try pour les méthodes que vous allez définir ultérieurement, puis chargez l’image et convertissez-la en octets à l’aide de 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();
    }

}

Installer la bibliothèque de client

Ce guide de démarrage rapide utilise le gestionnaire de dépendances Gradle. Vous trouverez la bibliothèque de client et des informations concernant d’autres gestionnaires de dépendances sur le référentiel central Maven.

Dans le fichier build.gradle.kts de votre projet, veillez à inclure la bibliothèque de client en tant qu’instruction 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")
}

Exemples de code

Ces extraits de code montrent comment effectuer les tâches suivantes avec la bibliothèque de client Recherche visuelle Bing et Java :

Authentifier le client

Notes

Ce guide de démarrage rapide part du principe que vous avez créé une variable d’environnement pour votre clé Recherche visuelle Bing, nommée BING_SEARCH_V7_SUBSCRIPTION_KEY.

Dans votre méthode principale, veillez à utiliser votre clé d’abonnement pour instancier un objet BingVisualSearchAPI.

BingVisualSearchAPI client = BingVisualSearchManager.authenticate(subscriptionKey);

Envoyer une demande de recherche visuelle

Dans une nouvelle méthode, envoyez le tableau d’octets d’image (créé dans la méthode main()) à l’aide de la méthode bingImages().visualSearch() du client.

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

}

Vérifiez si l’objet ImageKnowledge a la valeur null. Si ce n’est pas le cas, imprimez le jeton insights de l’image, le nombre d’étiquettes, le nombre d’actions et le premier type d’action.

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

Exécution de l'application

Vous pouvez générer l’application avec :

gradle build

Exécutez l’application avec l’objectif run :

gradle run

Nettoyer les ressources

Si vous souhaitez nettoyer et supprimer un abonnement Azure AI services, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées.

Étapes suivantes

Utilisez ce guide de démarrage rapide pour commencer à obtenir des insights sur les images à partir du service Recherche visuelle Bing, en utilisant la bibliothèque de client JavaScript. Si l’outil Recherche visuelle Bing dispose d’une API REST compatible avec la plupart des langages de programmation, la bibliothèque de client offre quant à elle un moyen simple d’intégrer le service à vos applications. Le code source de cet exemple est disponible sur GitHub.

Documentation de référence | | Package (NPM) | Échantillons

Prérequis

  • La dernière version de Node.js.
  • Le SDK Recherche visuelle Bing pour JavaScript
    • Pour l’installer, exécutez npm install @azure/cognitiveservices-visualsearch
  • La classe CognitiveServicesCredentials du package @azure/ms-rest-azure-js pour authentifier le client.
    • Pour l’installer, exécutez npm install @azure/ms-rest-azure-js

Créer une ressource Azure

Commencez à utiliser l’API Recherche visuelle Bing en créant une des ressources Azure suivantes :

Ressource Recherche Bing v7

  • Disponible via le portail Azure jusqu’à ce que vous supprimiez la ressource.
  • Sélectionnez le niveau tarifaire S9.

Ressource multiservice

  • Disponible via le portail Azure jusqu’à ce que vous supprimiez la ressource.
  • Utilisez la même clé et le même point de terminaison pour vos applications, sur plusieurs services Azure AI.

Créer et initialiser l’application

  1. Créez un fichier JavaScript dans votre éditeur ou IDE favori, puis ajoutez les exigences suivantes. Créez ensuite des variables pour votre clé d’abonnement, votre ID de configuration personnalisée et le chemin d’accès à l’image que vous souhaitez charger.

    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";
    
  2. Instanciez le client.

    let visualSearchClient = new Search.VisualSearchClient(credentials);
    

Rechercher des images

  1. Utilisez fs.createReadStream() pour lire le contenu de votre fichier image et créez des variables pour votre demande et vos résultats de recherche. Utilisez ensuite le client pour rechercher des images.

    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);
    }
    
  2. Analysez les résultats de la requête précédente :

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

Étapes suivantes

Utilisez ce guide de démarrage rapide pour commencer à obtenir des insights sur les images à partir du service Recherche visuelle Bing, en utilisant la bibliothèque de client Python. Si l’outil Recherche visuelle Bing dispose d’une API REST compatible avec la plupart des langages de programmation, la bibliothèque de client offre quant à elle un moyen simple d’intégrer le service à vos applications. Le code source de cet exemple est disponible sur GitHub.

Documentation de référence | Code source de la bibliothèque | Package (PyPi) | Exemples

Prérequis

  • Python 2.x ou 3.x
  • Il est recommandé d’utiliser un environnement virtuel. Installez et initialisez l’environnement virtuel avec le module venv.
  • La bibliothèque de client Recherche visuelle Bing pour Python. Vous pouvez l’installer à l’aide des commandes suivantes :
    1. cd mytestenv
    2. python -m pip install azure-cognitiveservices-search-visualsearch

Créer une ressource Azure

Commencez à utiliser l’API Recherche visuelle Bing en créant une des ressources Azure suivantes :

Ressource Recherche Bing v7

  • Disponible via le portail Azure jusqu’à ce que vous supprimiez la ressource.
  • Sélectionnez le niveau tarifaire S9.

Ressource multiservice

  • Disponible via le portail Azure jusqu’à ce que vous supprimiez la ressource.
  • Utilisez la même clé et le même point de terminaison pour vos applications, sur plusieurs services Azure AI.

Créer et initialiser l’application

  1. Créez un fichier Python dans votre éditeur ou IDE favori, puis ajoutez les instructions d’importation suivantes.

    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
    
  2. Créez des variables pour votre clé d’abonnement, votre ID de configuration personnalisée et l’image que vous souhaitez charger.

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

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

Envoyer la requête de recherche

  1. Une fois le fichier image ouvert, sérialisez VisualSearchRequest()et définissez-le comme paramètre knowledge_request pour 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)
    
  2. Si des résultats sont retournés, imprimez-les avec les balises et les actions contenues dans la première balise.

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

Étapes suivantes