Quickstart: Digitaal handschrift herkennen met de Ink Recognizer-REST API en C#

Artikel
08/24/2020

Notitie

De preview van de Ink Recognizer-API is op 26 augustus 2020 beëindigd. Als u bestaande Ink Recognizer-resources hebt, kunt u die blijven gebruiken totdat de service volledig wordt beëindigd op 31 januari 2021.

Gebruik deze quickstart om te beginnen met digitale pennenstreken naar de Ink Recognizer-API te verzenden. Met deze C#-toepassing wordt een API-aanvraag met gegevens over de pennenstreken met JSON-indeling verstuurd en het antwoord ontvangen.

Hoewel deze toepassing in C# is geschreven, is de API een RESTful-webservice die compatibel is met vrijwel elke programmeertaal.

Normaal gesproken zou u de API aanroepen vanuit een digitaal handschrift-app. In deze quickstart wordt gegevens over pennenstreken voor het volgende handgeschreven voorbeeld verzonden vanuit een JSON-bestand.

een afbeelding van handgeschreven tekst

De broncode voor deze quickstart is te vinden op GitHub.

Vereisten

Elke versie van Visual Studio 2017.
Newtonsoft.Json
- Newtonsoft.json installeren als een NuGet-pakket in Visual Studio:
  1. Klik met de rechtermuisknop op de Solution Manager
  2. Klik op NuGet-pakketten beheren...
  3. Zoeken naar Newtonsoft.Json en het pakket installeren
Als u Linux/MacOS gebruikt, kan deze toepassing worden uitgevoerd met behulp van Mono.
De voorbeeldgegevens over pennenstreken voor deze quickstart vindt u op GitHub.

Een Ink Recognizer-resource maken

Notitie

Voor eindpunten voor resources die zijn gemaakt na 1 juli 2019 wordt de aangepaste indeling voor subdomeinen gebruikt die hieronder wordt weergegeven. Zie Aangepaste subdomeinnamen voor Cognitive Services voor meer informatie en een volledige lijst met regionale eindpunten.

Azure Cognitive Services worden vertegenwoordigd door Azure-resources waarop u zich abonneert. Maak een resource voor Ink Recognizer met behulp van Azure Portal.

Nadat u een resource hebt gemaakt, haalt u uw eindpunt en sleutel op door uw resource te openen in Azure Portal en op Quickstart te klikken.

Maak twee omgevingsvariabelen:

INK_RECOGNITION_SUBSCRIPTION_KEY: de abonnementssleutel voor het verifiëren van uw aanvragen.
INK_RECOGNITION_ENDPOINT: het eindpunt voor uw resource. Dit zal er als volgt uitzien:
https://<your-custom-subdomain>.api.cognitive.microsoft.com

Een nieuwe toepassing maken

Maak in Visual Studio een nieuwe consoleoplossing en voeg de volgende pakketten toe.

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;

Maak variabelen voor uw abonnementssleutel, eindpunt en het JSON-voorbeeldbestand. Het eindpunt zal later worden gecombineerd met inkRecognitionUrl om toegang te krijgen tot de API.

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

Een functie maken voor het verzenden van aanvragen

Maak een nieuwe asynchrone functie met de naam Request die de hierboven gemaakte variabelen gebruikt.
Stel het beveiligingsprotocol en de headergegevens van de client in met behulp van een HttpClient-object. Vergeet niet om de abonnementssleutel toe te voegen aan de Ocp-Apim-Subscription-Key-header. Maak vervolgens een StringContent-object voor de aanvraag.

Verzend de aanvraag met PutAsync(). Als de aanvraag is voltooid, retourneert u het antwoord.

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

Een aanvraag voor handschriftherkenning verzenden

Maak een nieuwe functie met de naam recognizeInk(). Stel de aanvraag op en verzend deze door de Request()-functie aan te roepen met uw eindpunt, de abonnementssleutel, de URL voor de API en de gegevens van digitale pennenstreken.

Deserialiseer het JSON-object en schrijf het naar de console.

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

Uw digitale handschriftgegevens laden

Maak een functie met de naam LoadJson() om het JSON-bestand met de handschriftgegevens te laden. Gebruik een StreamReader en JsonTextReader om een JObject te maken en het te retourneren.

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

De API-aanvraag verzenden

In de hoofdmethode van uw toepassing laadt u uw JSON-gegevens met de hierboven gemaakte functie.

Roep de hierboven gemaakte recognizeInk()-functie aan. Gebruik System.Console.ReadKey() om het consolevenster geopend te houden nadat de toepassing is uitgevoerd.

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

De toepassing uitvoeren en het antwoord bekijken

Voer de toepassing uit. Er wordt een geslaagd antwoord geretourneerd in JSON-indeling. U kunt ook het JSON-antwoord vinden op GitHub.

Volgende stappen

Naslaginformatie over REST API

Bekijk de volgende voorbeeldtoepassingen op GitHub voor meer informatie over de werking van de Ink Recognition-API in een app voor digitaal handschrift: