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

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. Die hier verwendete JavaScript-Anwendung sendet eine API-Anforderung, die JSON-formatierte Freihandstrichdaten enthält, und zeigt die Antwort an.

Diese Anwendung ist zwar in JavaScript geschrieben und wird im Webbrowser ausgeführt, an sich ist die API aber 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

Aus einem Webbrowser
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 integrierten Entwicklungsumgebung (Integrated Devlopment Environment, IDE) oder Ihrem bevorzugten Editor eine neue .html-Datei. Fügen Sie anschließend eine grundlegende HTML-Struktur hinzu. Den Code fügen wir später hinzu.
```
<!DOCTYPE html>
<html>

    <head>
        <script type="text/javascript">
        </script>
    </head>

    <body>
    </body>

</html>
```

Fügen Sie innerhalb des <body>-Tags den folgenden HTML-Code hinzu:

Zwei Textbereiche für die Anzeige der JSON-Anforderung und -Antwort
Eine Schaltfläche zum Aufrufen der recognizeInk()-Funktion, die später erstellt wird

<!-- <body>-->
    <h2>Send a request to the Ink Recognition API</h2>
    <p>Request:</p>
    <textarea id="request" style="width:800px;height:300px"></textarea>
    <p>Response:</p>
    <textarea id="response" style="width:800px;height:300px"></textarea>
    <br>
    <button type="button" onclick="recognizeInk()">Recognize Ink</button>
<!--</body>-->

Laden der JSON-Beispieldaten

Erstellen Sie innerhalb des <script>-Tags eine Variable für die JSON-Beispieldaten (sampleJson). Erstellen Sie dann eine JavaScript-Funktion mit dem Namen openFile(), die einen Datei-Explorer öffnet, in dem Sie die JSON-Datei auswählen können. Wenn auf die Schaltfläche Recognize ink geklickt wird, wird diese Funktion aufgerufen und die Datei gelesen.

Verwenden Sie die onload()-Funktion eines FileReader-Objekts, um die Datei asynchron zu verarbeiten.

Ersetzen Sie alle \n- oder \r-Zeichen in der Datei durch eine leere Zeichenfolge.
Konvertieren Sie den Text mithilfe von JSON.parse() in ein gültiges JSON-Format.
Aktualisieren Sie das Textfeld request in der Anwendung. Formatieren Sie die JSON-Zeichenfolge mit JSON.stringify().

var sampleJson = "";
function openFile(event) {
    var input = event.target;

    var reader = new FileReader();
    reader.onload = function(){
        sampleJson = reader.result.replace(/(\\r\\n|\\n|\\r)/gm, "");
        sampleJson = JSON.parse(sampleJson);
        document.getElementById('request').innerHTML = JSON.stringify(sampleJson, null, 2);
    };
    reader.readAsText(input.files[0]);
};

Senden einer Anforderung an die Freihanderkennungs-API

Erstellen Sie innerhalb des <script>-Tags eine Funktion mit dem Namen recognizeInk(). Diese Funktion ruft später die API auf und aktualisiert die Seite mit der Antwort. Fügen Sie den Code aus den folgenden Schritten in dieser Funktion hinzu.

function recognizeInk() {
// add the code from the below steps here 
}

Erstellen Sie Variablen für Ihre Endpunkt-URL, Ihren Abonnementschlüssel und die JSON-Beispieldaten. Erstellen Sie dann ein XMLHttpRequest-Objekt, um die API-Anforderung senden.

// Replace the below URL with the correct one for your subscription. 
// Your endpoint can be found in the Azure portal. For example: "https://<your-custom-subdomain>.cognitiveservices.azure.com";
var SERVER_ADDRESS = process.env["INK_RECOGNITION_ENDPOINT"];
var ENDPOINT_URL = SERVER_ADDRESS + "/inkrecognizer/v1.0-preview/recognize";
var SUBSCRIPTION_KEY = process.env["INK_RECOGNITION_SUBSCRIPTION_KEY"];
var xhttp = new XMLHttpRequest();

Erstellen Sie die Rückgabefunktion für das XMLHttpRequest-Objekt. Diese Funktion analysiert die API-Antwort einer erfolgreichen Anforderung und zeigt sie in der Anwendung an.

function returnFunction(xhttp) {
    var response = JSON.parse(xhttp.responseText);
    console.log("Response: %s ", response);
    document.getElementById('response').innerHTML = JSON.stringify(response, null, 2);
}

Erstellen Sie die Fehlerfunktion für das Anforderungsobjekt. Diese Funktion protokolliert den Fehler in der Konsole.
```
function errorFunction() {
    console.log("Error: %s, Detail: %s", xhttp.status, xhttp.responseText);
}
```
Erstellen Sie eine Funktion für die onreadystatechange-Eigenschaft des Anforderungsobjekts. Wenn sich der Bereitschaftszustand des Anforderungsobjekts ändert, werden die obigen Rückgabe- und Fehlerfunktionen angewendet.
```
xhttp.onreadystatechange = function () {
    if (this.readyState === 4) {
        if (this.status === 200) {
            returnFunction(xhttp);
        } else {
            errorFunction(xhttp);
        }
    }
};
```

Senden Sie die API-Anforderung. Fügen Sie dem Header Ocp-Apim-Subscription-Key Ihren Abonnementschlüssel hinzu, und legen Sie content-type auf application/json fest.

xhttp.open("PUT", ENDPOINT_URL, true);
xhttp.setRequestHeader("Ocp-Apim-Subscription-Key", SUBSCRIPTION_KEY);
xhttp.setRequestHeader("content-type", "application/json");
xhttp.send(JSON.stringify(sampleJson));
};

Ausführen der Anwendung und Anzeigen der Antwort

Diese Anwendung kann in Ihrem Webbrowser ausgeführt werden. 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: