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

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 à envoyer des traits d’encre numérique à l’API Ink Recognizer. Cette application C# 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 C#, 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

N’importe quelle édition de Visual Studio 2017.
Newtonsoft.Json
- Pour installer Newtonsoft.Json en tant que package NuGet dans Visual Studio :
  1. Cliquez avec le bouton droit sur le Gestionnaire de solution.
  2. Cliquez sur Gérer les packages NuGet...
  3. Recherchez Newtonsoft.Json et installez le package.
Si vous utilisez Linux/MacOS, cette application peut être exécutée à l’aide de Mono.
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

Dans Visual Studio, créez une solution de console et ajoutez les packages suivants.

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;

Créez des variables pour votre point de terminaison et votre clé d’abonnement, ainsi que l’exemple de fichier JSON. Le point de terminaison sera combiné ultérieurement avec inkRecognitionUrl pour accéder à l’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";

Créer une fonction pour envoyer des requêtes

Créez une fonction asynchrone appelée Request qui prend les variables créées plus haut.
Définissez le protocole de sécurité et les informations d’en-tête du client à l’aide d’un objet HttpClient. Veillez à ajouter votre clé d’abonnement à l’en-tête Ocp-Apim-Subscription-Key. Créez ensuite un objet StringContent pour la requête.

Ensuite, envoyez la requête avec PutAsync(). Si la requête réussit, retournez la réponse.

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

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

Créez une fonction appelée recognizeInk(). Construisez la requête et envoyez-la en appelant la fonction Request() avec votre point de terminaison, la clé d’abonnement, l’URL de l’API et les données du trait d’encre numérique.

Désérialisez l’objet JSON et écrivez-le dans la 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);
}

Charger vos données d’encre numérique

Créez une fonction appelée LoadJson() pour charger le fichier JSON de données d’encre. Utilisez un StreamReader et un JsonTextReader pour créer un JObject et retournez-le.

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

Envoyer la requête d’API

Dans la méthode Main de votre application, chargez vos données JSON avec la fonction créée plus haut.

Appelez la fonction recognizeInk() créée plus haut. Utilisez System.Console.ReadKey() pour maintenir la fenêtre de console ouverte après l’exécution de l’application.

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

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 :