Schnellstart: Erkennen von Freihandeingaben mit der Freihanderkennungs-REST-API und Java

Artikel
08/24/2020

Hinweis

Die Vorschauversion der Freihanderkennungs-API ist am 26. August 2020 abgelaufen. Wenn Sie über vorhandene Freihanderkennungsressourcen verfügen, können Sie sie weiterhin verwenden, bis der Dienst am 31. Januar 2021 endgültig eingestellt wird.

In diesem Schnellstart werden die ersten Schritte zur Verwendung der Freihanderkennungs-API zum Erkennen von Freihandstrichen erläutert. Diese Java-Anwendung sendet eine API-Anforderung, die JSON-formatierte Freihandstrichdaten enthält, und erhält die Antwort.

Diese Anwendung ist in Java geschrieben, die API ist jedoch ein RESTful-Webdienst, der mit den meisten Programmiersprachen kompatibel ist.

Normalerweise würden Sie die API über eine App für Freihandeingabe aufrufen. In diesem Schnellstart werden Freihandstrichdaten für das folgende handschriftliche Beispiel aus einer JSON-Datei gesendet.

Abbildung, die handschriftlichen Text zeigt

Den Quellcode für diese Schnellstartanleitung finden Sie auf GitHub.

Voraussetzungen

Das Java™ Development Kit(JDK) 7 oder höher.
Importieren dieser Bibliotheken aus dem Maven-Repository
- Paket JSON in Java
- Paket Apache HttpClient
Die Beispiel-Freihandstrichdaten für diesen Schnellstart finden Sie auf GitHub.

Erstellen einer Freihanderkennungsressource

Hinweis

Nach dem 1. Juli 2019 erstellte Endpunkte nutzen das unten gezeigte benutzerdefinierte Format für Subdomänen. Weitere Informationen und eine vollständige Liste mit regionalen Endpunkten finden Sie unter Benutzerdefinierte Unterdomänennamen für Cognitive Services.

Azure Cognitive Services werden von Azure-Ressourcen dargestellt, die Sie abonnieren. Erstellen Sie im Azure-Portal eine Ressource für die Freihanderkennung.

Rufen Sie nach dem Erstellen einer Ressource den Endpunkt und den Schlüssel ab, indem Sie die Ressource im Azure-Portal öffnen und auf Schnellstart klicken.

Erstellen Sie zwei Umgebungsvariablen:

INK_RECOGNITION_SUBSCRIPTION_KEY: Der Abonnementschlüssel zum Authentifizieren Ihrer Anforderungen
INK_RECOGNITION_ENDPOINT: Der Endpunkt für die Ressource. Er sieht wie folgt aus:
https://<your-custom-subdomain>.api.cognitive.microsoft.com

Erstellen einer neuen Anwendung

Erstellen Sie in Ihrer bevorzugten IDE oder in Ihrem bevorzugten Editor ein neues Java-Projekt, und importieren Sie die folgenden Bibliotheken.

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;

Erstellen Sie Variablen für Ihren Abonnementschlüssel, den Endpunkt und die JSON-Datei. Der Endpunkt wird später an den Freihanderkennungs-URI angehängt.

// 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";

Erstellen einer Funktion zum Senden von Anforderungen

Erstellen Sie eine neuen Funktion namens sendRequest(), die die oben erstellten Variablen verwendet. Führen Sie anschließend die folgenden Schritte aus.
Erstellen Sie ein CloseableHttpClient-Objekt, das Anforderungen an die API senden kann. Senden Sie die Anforderung an ein HttpPut-Anforderungsobjekt, indem Sie Ihren Endpunkt und die URL der Freihanderkennung kombinieren.
Verwenden Sie die Funktion setHeader() der Anforderung, um den Header Content-Type auf application/json festzulegen, und fügen Sie Ihren Abonnementschlüssel dem Header Ocp-Apim-Subscription-Key hinzu.
Verwenden Sie die Funktion setEntity() der Anforderung für die zu sendenden Daten.
Verwenden Sie die Funktion execute() des Clients, um die Anforderung zu senden, und speichern Sie sie in einem CloseableHttpResponse-Objekt.

Erstellen Sie ein HttpEntity-Objekt, um den Inhalt der Antwort zu speichern. Rufen Sie den Inhalt mit getEntity() ab. Wenn die Antwort nicht leer ist, geben Sie sie zurück.

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

Senden einer Freihanderkennungsanforderung

Erstellen Sie eine Methode namens recognizeInk() zur Erkennung Ihrer Freihandstrichdaten. Rufen Sie die oben erstellte Methode sendRequest() mit dem Endpunkt, der URL, dem Abonnementschlüssel und den JSON-Daten auf. Rufen Sie das Ergebnis ab, und geben Sie es in der Konsole aus.

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

Laden der digitalen Freihanddaten und Senden der Anforderung

Lesen Sie in der Hauptmethode Ihrer Anwendung die JSON-Datei mit den Daten ein, die den Anforderungen hinzugefügt werden.

Rufen Sie die oben erstellte Freihanderkennungsfunktion auf.

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

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

Ausführen der Anwendung und Anzeigen der Antwort

Führen Sie die Anwendung aus. Eine erfolgreiche Antwort wird im JSON-Format zurückgegeben. Sie finden die JSON-Antwort auch auf GitHub.

Nächste Schritte

REST-API-Referenz

Sehen Sie sich in den folgenden Beispielanwendungen auf GitHub an, wie die Freihanderkennungs-API in einer Freihandschriftinhalte-App funktioniert:

Freigeben über