Início Rápido: Reconhecer tinta digital com a API REST de Reconhecimento de Tinta Digital e o C#

Artigo
08/24/2020

Observação

A API do Reconhecimento de Tinta Digital encerrou a versão prévia em 26 de agosto de 2020. Se você tiver recursos existentes do Reconhecimento de Tinta Digital, poderá continuar a usá-los até que o serviço seja totalmente desativado em 31 de janeiro de 2021.

Use este início rápido para começar a enviar traços de tinta digital para a API de Reconhecimento de Tinta Digital. Este aplicativo C# envia uma solicitação de API que contém dados de traço de tinta formatados em JSON e obtém a resposta.

Embora esse aplicativo seja escrito em C#, a API é um serviço Web RESTful compatível com a maioria das linguagens de programação.

Normalmente, você chamará a API em um aplicativo de escrita à tinta digital. Este início rápido envia dados de traço de tinta para a amostra manuscrita a seguir de um arquivo JSON.

uma imagem de um texto manuscrito

O código-fonte deste Início Rápido pode ser encontrado no GitHub.

Pré-requisitos

Qualquer edição do Visual Studio 2017.
Newtonsoft.Json
- Para instalar o Newtonsoft.Json como um pacote NuGet no Visual Studio:
  1. Clique com o botão direito do mouse no Gerenciador de Soluções
  2. Clique em Gerenciar Pacotes NuGet...
  3. Pesquise Newtonsoft.Json e instale o pacote
Se você estiver usando o Linux/macOS, esse aplicativo poderá ser executado com o Mono.
Os dados de traço de tinta de exemplo deste início rápido podem ser encontrados no GitHub.

Criar um recurso do Reconhecimento de Tinta Digital

Observação

Pontos de extremidade para recursos criados após 1º de julho de 2019, use o formato de subdomínio personalizado mostrado abaixo. Para saber mais e para obter uma lista completa de pontos de extremidade regionais, confira Nomes de subdomínio personalizados para Serviços Cognitivos.

Os Serviços Cognitivos do Azure são representados por recursos do Azure que você assina. Crie um recurso para o Reconhecimento de Tinta Digital usando o portal do Azure.

Depois de criar um recurso, obtenha o ponto de extremidade e a chave abrindo o recurso no portal do Azure e clicando em Início rápido.

Criar duas variáveis de ambiente:

INK_RECOGNITION_SUBSCRIPTION_KEY – A chave de assinatura para autenticar suas solicitações.
INK_RECOGNITION_ENDPOINT – O ponto de extremidade para seu recurso. Ele terá esta aparência:
https://<your-custom-subdomain>.api.cognitive.microsoft.com

Crie um novo aplicativo

No Visual Studio, crie uma solução de console e adicione os pacotes a seguir.

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;

Crie variáveis para a chave de assinatura, o ponto de extremidade e o arquivo JSON de exemplo. O ponto de extremidade posteriormente será combinado com inkRecognitionUrl para acessar a 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";

Criar uma função para enviar solicitações

Crie uma função assíncrona chamada Request que usa as variáveis criadas acima.
Defina o protocolo de segurança do cliente e as informações de cabeçalho usando um objeto HttpClient. Adicione a chave de assinatura ao cabeçalho Ocp-Apim-Subscription-Key. Em seguida, crie um objeto StringContent para a solicitação.

Envie a solicitação com PutAsync(). Se a solicitação for bem-sucedida, retorne a resposta.

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

Enviar uma solicitação de reconhecimento de tinta

Crie uma função chamada recognizeInk(). Construa a solicitação e envie-a chamando a função Request() com o ponto de extremidade, a chave de assinatura, a URL para a API e os dados de traço de tinta digital.

Desserialize o objeto JSON e grave-o no 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);
}

Carregar os dados de tinta digital

Crie uma função chamada LoadJson() para carregar o arquivo JSON de dados de tinta. Use um StreamReader e um JsonTextReader para criar um JObject e retorne-o.

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

Enviar a solicitação de API

No método principal do aplicativo, carregue os dados JSON com a função criada acima.

Chame a função recognizeInk() criada acima. Use System.Console.ReadKey() para manter a janela do console aberta depois de executar o aplicativo.

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

Executar o aplicativo e exibir a resposta

Execute o aplicativo. Uma resposta bem-sucedida é retornada no formato JSON. Você também pode encontrar a resposta JSON no GitHub.

Próximas etapas

Referência da API REST

Para ver como a API do Reconhecimento de Tinta Digital funciona em um aplicativo de escrita à tinta digital, vejamos os seguintes aplicativos de exemplo no GitHub:

Compartilhar via