Démarrage rapide : Reconnaître l’encre numérique avec l’API REST Ink Recognizer et Java

Article
08/24/2020

Notes

La préversion de l’API Ink Recognizer a pris fin le 26 août 2020. Si vous avez des ressources Ink Recognizer, vous pouvez continuer à les utiliser jusqu’au retrait total du service le 31 janvier 2021.

Utilisez ce guide de démarrage rapide pour commencer à appliquer l’API Ink Recognizer aux traits d’encre numérique. Cette application Java envoie une requête d’API contenant des données de trait d’encre au format JSON, puis obtient la réponse.

Bien que cette application soit écrite en Java, l’API est un service web RESTful compatible avec la plupart des langages de programmation.

En règle générale, vous appelez l’API à partir d’une application d’écriture manuscrite numérique. Ce guide de démarrage rapide envoie des données de trait d’encre pour l’exemple d’écriture manuscrite suivant à partir d’un fichier JSON.

une image de texte manuscrit

Le code source de ce guide de démarrage rapide est disponible sur GitHub.

Prérequis

Kit de développement Java™ (JDK) 7 ou version ultérieure.
Importez ces bibliothèques à partir du référentiel Maven :
- Package JSON en Java
- Package Apache HttpClient
Vous trouverez l’exemple de données de trait d’encre utilisé dans ce guide de démarrage rapide sur GitHub.

Créer une ressource Ink Recognizer

Notes

Les points de terminaison pour les ressources créées après le 1er juillet 2019 utilisent le format de sous-domaine personnalisé indiqué ci-dessous. Pour obtenir plus d’informations et une liste complète des points de terminaison régionaux, consultez Noms de sous-domaines personnalisés pour Cognitive Services.

Les services Azure Cognitive Services sont représentés par des ressources Azure auxquelles vous vous abonnez. Créez une ressource pour Ink Recognizer à l’aide du portail Azure.

Après avoir créé une ressource, obtenez votre point de terminaison et votre clé en ouvrant votre ressource dans le portail Azure puis en cliquant sur Démarrage rapide.

Créez deux variables d’environnement :

INK_RECOGNITION_SUBSCRIPTION_KEY : la clé d’abonnement pour l’authentification de vos requêtes.
INK_RECOGNITION_ENDPOINT : le point de terminaison de votre ressource. Il se présente comme suit :
https://<your-custom-subdomain>.api.cognitive.microsoft.com

Créer une application

Créez un projet Java dans votre éditeur ou IDE favori, puis importez les bibliothèques suivantes.

import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import com.fasterxml.jackson.core.JsonParseException;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

Créez des variables pour votre clé d’abonnement, votre point de terminaison et votre fichier JSON. Le point de terminaison sera ajouté ultérieurement à l’URI Ink recognizer.

// Add your Azure Ink Recognition subscription key to your environment variables.
private static final String subscriptionKey = System.getenv("INK_RECOGNITION_SUBSCRIPTION_KEY");

// Add your Azure Ink Recognition endpoint to your environment variables.
public static final String rootUrl = System.getenv("INK_RECOGNITION_ENDPOINT");
public static final String inkRecognitionUrl = "/inkrecognizer/v1.0-preview/recognize";
// Replace the dataPath string with a path to the JSON formatted ink stroke data file.
private static final String dataPath = "PATH_TO_INK_STROKE_DATA";

Créer une fonction pour envoyer des requêtes

Créez une fonction appelée sendRequest() qui sélectionne les variables créées précédemment. Ensuite, effectuez les étapes suivantes.
Créez un objet CloseableHttpClient qui peut envoyer des requêtes à l’API. Envoyez la requête à un objet de requête HttpPut en combinant votre point de terminaison et l’URL Ink Recognizer.
Utilisez la fonction setHeader() de la requête pour affecter la valeur application/json à l’en-tête Content-Type, et ajoutez votre clé d’abonnement à l’en-tête Ocp-Apim-Subscription-Key.
Utilisez la fonction setEntity() de la requête sur les données à envoyer.
Utilisez la fonction execute() du client pour envoyer la requête, et enregistrez-la dans un objet CloseableHttpResponse.

Créez un objet HttpEntity pour stocker le contenu de la réponse. Obtenez le contenu avec getEntity(). Si la réponse n’est pas vide, retournez-la.

static String sendRequest(String endpoint, String apiAddress, String subscriptionKey, String requestData) {
    try (CloseableHttpClient client = HttpClients.createDefault()) {
        HttpPut request = new HttpPut(endpoint + apiAddress);
        // Request headers.
        request.setHeader("Content-Type", "application/json");
        request.setHeader("Ocp-Apim-Subscription-Key", subscriptionKey);
        request.setEntity(new StringEntity(requestData));
        try (CloseableHttpResponse response = client.execute(request)) {
            HttpEntity respEntity = response.getEntity();
            if (respEntity != null) {
                return EntityUtils.toString(respEntity, "utf-8");
            }
        } catch (Exception respEx) {
            respEx.printStackTrace();
        }
    } catch (IOException ex) {
        System.err.println("Exception on Anomaly Detector: " + ex.getMessage());
        ex.printStackTrace();
    }
    return null;
}

Envoyer une requête de reconnaissance de l’écriture manuscrite

Créez une méthode appelée recognizeInk() pour reconnaître vos données de trait d’encre. Appelez la méthode sendRequest() créée ci-dessus avec votre point de terminaison, l’URL, la clé d’abonnement et les données JSON. Obtenez le résultat et imprimez-le dans la console.

static void recognizeInk(String requestData) {
    System.out.println("Sending an Ink recognition request.");

    String result = sendRequest(rootUrl, inkRecognitionUrl, subscriptionKey, requestData);
    
    // Pretty-print the JSON result
    try {
        ObjectMapper objectMapper = new ObjectMapper();
        Map<String, Object> response = objectMapper.readValue(result, HashMap.class);
        System.out.println(objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(response));
    } catch (JsonParseException e) {
        e.printStackTrace();
    } catch (JsonMappingException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }  
}

Charger vos données d’encre numérique et envoyer la requête

Dans la méthode Main de votre application, lisez le fichier JSON contenant les données qui seront ajoutées aux requêtes.

Appelez la fonction de reconnaissance de l’écriture manuscrite créée ci-dessus.

public static void main(String[] args) throws Exception {

    String requestData = new String(Files.readAllBytes(Paths.get(dataPath)), "utf-8");
    recognizeInk(requestData);
}

Exécuter l’application et afficher la réponse

Exécutez l'application. Une réponse correcte est retournée au format JSON. Vous pouvez également trouver la réponse JSON sur GitHub.

Étapes suivantes

Référence d’API REST

Pour observer le fonctionnement de l’API Ink Recognizer dans une application d’écriture manuscrite numérique, examinez les exemples d’applications suivants sur GitHub :

Partager via