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

  • Artikel

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 zum Senden von Freihandstrichen an die Freihanderkennungs-API erläutert. Diese C#-Anwendung sendet eine API-Anforderung, die JSON-formatierte Freihandstrichdaten enthält, und erhält die Antwort.

Die Anwendung ist zwar in C# geschrieben, 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

  • Eine beliebige Visual Studio 2017-Edition.

  • Newtonsoft.Json

    • So installieren Sie Newtonsoft.Json als NuGet-Paket in Visual Studio
      1. Klicken Sie im Projektmappen-Manager mit der rechten Maustaste.
      2. Klicken Sie auf Manage NuGet Packages
      3. Suchen Sie nach Newtonsoft.Json, und installieren Sie das Paket.

  • Unter Linux/MacOS kann diese Anwendung mit Mono ausgeführt werden.

  • 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

  1. Erstellen Sie in Visual Studio eine neue Konsolenprojektmappe, und fügen Sie die folgenden Pakete hinzu.

    using System;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

  2. Erstellen Sie Variablen für den Abonnementschlüssel und -endpunkt und die JSON-Beispieldatei. Der Endpunkt wird später für den Zugriff auf die API mit inkRecognitionUrl kombiniert.

    // Add your Ink Recognizer subscription key to your environment variables.
static readonly string subscriptionKey = Environment.GetEnvironmentVariable("INK_RECOGNIZER_SUBSCRIPTION_KEY");

// Add your Ink Recognizer endpoint to your environment variables.
// For example: <your-custom-subdomain>.cognitiveservices.azure.com
static readonly string endpoint = Environment.GetEnvironmentVariable("INK_RECOGNIZER_ENDPOINT");
static readonly string inkRecognitionUrl = "/inkrecognizer/v1.0-preview/recognize";

// Replace the dataPath string with a path to the JSON formatted ink stroke data.
// Optionally, use the example-ink-strokes.json file of this sample. Add to your bin\Debug\netcoreapp3.0 project folder.
static readonly string dataPath = @"PATH_TO_INK_STROKE_DATA";

Erstellen einer Funktion zum Senden von Anforderungen

  1. Erstellen Sie eine neuen asynchronen Funktion namens Request, die die oben erstellten Variablen verwendet.

  2. Legen Sie das Sicherheitsprotokoll und die Headerinformationen des Clients mithilfe eines HttpClient-Objekts fest. Achten Sie darauf, dass Sie dem Header Ocp-Apim-Subscription-Key Ihren Abonnementschlüssel hinzufügen. Erstellen Sie dann ein StringContent-Objekt für die Anforderung.

  3. Senden Sie die Anforderung mit PutAsync(). Wenn die Anforderung erfolgreich ist, geben Sie die Antwort zurück.

    static async Task<string> Request(string apiAddress, string endpoint, string subscriptionKey, string requestData)
{

    using (HttpClient client = new HttpClient { BaseAddress = new Uri(apiAddress) })
    {
        System.Net.ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12 | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls;
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
        client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);

        var content = new StringContent(requestData, Encoding.UTF8, "application/json");
        var res = await client.PutAsync(endpoint, content);
        if (res.IsSuccessStatusCode)
        {
            return await res.Content.ReadAsStringAsync();
        }
        else
        {
            return $"ErrorCode: {res.StatusCode}";
        }
    }
}

Senden einer Freihanderkennungsanforderung

  1. Erstellen Sie eine neue Funktion namens recognizeInk(). Erstellen Sie die Anforderung und senden Sie sie, indem Sie die Funktion Request() mit Ihrem Endpunkt, Ihrem Abonnementschlüssel, der URL für die API und den digitalen Freihandstrichdaten aufrufen.

  2. Deserialisieren Sie das JSON-Objekt, und schreiben Sie es in die Konsole.

    static void recognizeInk(string requestData)
{

    //construct the request
    var result = Request(
        endpoint,
        inkRecognitionUrl,
        subscriptionKey,
        requestData).Result;

    dynamic jsonObj = Newtonsoft.Json.JsonConvert.DeserializeObject(result);
    System.Console.WriteLine(jsonObj);
}

Laden der digitalen Freihanddaten

Erstellen Sie eine Funktion namens LoadJson(), um die Freihanddaten-JSON-Datei zu laden. Verwenden Sie ein StreamReader- und ein JsonTextReader-Element zum Erstellen eines JObject-Objekts, und geben Sie es zurück.

public static JObject LoadJson(string fileLocation)
{
    var jsonObj = new JObject();

    using (StreamReader file = File.OpenText(fileLocation))
    using (JsonTextReader reader = new JsonTextReader(file))
    {
        jsonObj = (JObject)JToken.ReadFrom(reader);
    }
    return jsonObj;
}

Senden der API-Anforderung

  1. Laden Sie in der Hauptmethode Ihrer Anwendung Ihre JSON-Daten mit der oben erstellten Funktion.

  2. Rufen Sie die oben erstellte recognizeInk()-Funktion auf. Verwenden Sie System.Console.ReadKey(), damit das Konsolenfenster nach dem Ausführen der Anwendung geöffnet bleibt.

    static void Main(string[] args)
{

    var requestData = LoadJson(dataPath);
    string requestString = requestData.ToString(Newtonsoft.Json.Formatting.None);
    recognizeInk(requestString);
    System.Console.WriteLine("\nPress any key to exit ");
    System.Console.ReadKey();
}

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: