Quickstart: Reconhecer tinta digital com a API e C do Reconhecimento de Tinta REST #

  • Artigo

Nota

A API do Reconhecimento de Tinta terminou a sua pré-estreia no dia 26 de agosto de 2020. Se tiver os recursos existentes do Ink Recogniser, pode continuar a usá-los até que o serviço seja totalmente reformado a 31 de janeiro de 2021.

Use este quickstart para começar a enviar traços de tinta digital para a API do Reconhecimento de Tinta. Esta aplicação C# envia um pedido de API contendo dados de traçado de tinta com formato JSON, e obtém a resposta.

Enquanto esta aplicação está escrita em C#, a API é um serviço web RESTful compatível com a maioria das linguagens de programação.

Normalmente, você chamaria a API de uma aplicação digital de tinta. Este quickstart envia dados de traçado de tinta para a seguinte amostra manuscrita a partir de um ficheiro JSON.

uma imagem de texto manuscrito

O código-fonte para este arranque rápido pode ser encontrado no GitHub.

Pré-requisitos

  • Qualquer edição do Visual Studio 2017.

  • Newtonsoft.Json

    • Para instalar Newtonsoft.Json como um pacote NuGet em estúdio visual:
      1. Clique no gestor de solução
      2. Clique em Gerir Pacotes NuGet...
      3. Procurar Newtonsoft.Json e instalar o pacote

  • Se estiver a utilizar o Linux/MacOS, esta aplicação pode ser executada utilizando o Mono.

  • Os dados de traçado de tinta de exemplo para este arranque rápido podem ser encontrados no GitHub.

Criar um recurso de Reconhecimento de Tinta

Nota

Os pontos finais para recursos criados após 1 de julho de 2019 utilizam o formato de subdomínio personalizado apresentado abaixo. Para mais informações e uma lista completa de pontos finais regionais, consulte os nomes de subdomínio personalizados para Serviços Cognitivos.

Os Serviços Cognitivos Azure são representados por recursos Azure que subscreve. Crie um recurso para o Reconhecimento de Tinta utilizando o portal do Azure.

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

Criar duas variáveis ambientais:

  • INK_RECOGNITION_SUBSCRIPTION_KEY - A chave de subscrição para autenticar os seus pedidos.

  • INK_RECOGNITION_ENDPOINT - O ponto final do seu recurso. Terá o seguinte aspeto:
    https://<your-custom-subdomain>.api.cognitive.microsoft.com

Criar uma nova aplicação

  1. No Visual Studio, crie uma nova solução de consola e adicione os seguintes pacotes.

    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. Crie variáveis para a sua chave de subscrição e ponto final, e o ficheiro JSON exemplo. O ponto final será posteriormente combinado com inkRecognitionUrl o acesso à 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 pedidos

  1. Crie uma nova função async chamada Request que leva as variáveis criadas acima.

  2. Desajei o protocolo de segurança do cliente e informações de cabeçalho usando um HttpClient objeto. Certifique-se de adicionar a chave de subscrição ao Ocp-Apim-Subscription-Key cabeçalho. Em seguida, criar um StringContent objeto para o pedido.

  3. Envie o pedido com PutAsync(). Se o pedido for bem sucedido, devolva 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 um pedido de reconhecimento de tinta

  1. Criar uma nova função chamada recognizeInk(). Construa o pedido e envie-o chamando a função com o Request() seu ponto final, chave de subscrição, o URL para a API e os dados digitais do traçado de tinta.

  2. Deserialize o objeto JSON e escreva-o para a consola.

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

Carregue os seus dados de tinta digital

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

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

Envie o pedido da API

  1. No método principal da sua aplicação, carregue os seus dados JSON com a função acima criada.

  2. Ligue para a recognizeInk() função criada acima. Utilize System.Console.ReadKey() para manter a janela da consola aberta depois de executar a aplicação.

    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 a aplicação e ver a resposta

Execute a aplicação. Uma resposta bem sucedida é devolvida no formato JSON. Também pode encontrar a resposta JSON no GitHub.

Passos seguintes

Referência da API REST

Para ver como funciona a API de Reconhecimento de Tinta numa aplicação digital de tinta, veja as seguintes aplicações de amostra no GitHub: