快速入门：使用墨迹识别器 REST API 和 C# 识别数字墨迹

项目
08/24/2020

注意

墨迹识别器 API 已于 2020 年 8 月 26 日结束预览。如果你目前有墨迹识别器资源，可继续使用它们，直到该服务于 2021 年 1 月 31 日被完全停用为止。

根据本快速入门的说明，开始将数字墨迹笔划发送到墨迹识别器 API。本 C# 应用程序发送包含 JSON 格式墨迹笔划数据的 API 请求，并获取响应。

虽然此应用程序是使用 C# 编写的，但 API 是一种 RESTful Web 服务，与大多数编程语言兼容。

通常会从数字墨迹应用调用此 API。本快速入门为 JSON 文件中的以下手写示例发送墨迹笔划数据。

手写文本图像

可以在 GitHub 上找到此快速入门的源代码。

先决条件

任何版本的 Visual Studio 2017。
Newtonsoft.Json
- 若要在 Visual Studio 中以 NuGet 包的形式安装 Newtonsoft.Json，请执行以下操作：
  1. 右键单击“解决方案管理器”
  2. 单击“管理 NuGet 包”。
  3. 搜索 Newtonsoft.Json 并安装该包
如果使用的是 Linux/MacOS，则可使用 Mono 运行此应用程序。
可以在 GitHub 上找到此快速入门的示例墨迹笔划数据。

创建“墨迹识别器”资源

注意

在 2019 年 7 月 1 日之后创建的资源的终结点使用如下所示的自定义子域格式。有关详细信息和区域终结点的完整列表，请参阅认知服务的自定义子域名。

Azure 认知服务由你订阅的 Azure 资源表示。使用 Azure 门户为墨迹识别器创建资源。

创建资源后，通过打开 Azure 门户上的资源并单击“快速入门”来获取终结点和密钥。

创建两个环境变量：

INK_RECOGNITION_SUBSCRIPTION_KEY - 用于对请求进行身份验证的订阅密钥。
INK_RECOGNITION_ENDPOINT - 资源的终结点。它将如下所示：
https://<your-custom-subdomain>.api.cognitive.microsoft.com

创建新应用程序

在 Visual Studio 中，创建新的控制台解决方案并添加以下包。

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;

为订阅密钥和终结点以及示例 JSON 文件创建变量。稍后，终结点将与 inkRecognitionUrl 结合使用来访问 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";

创建用于发送请求的函数

创建名为 Request 的新异步函数，该函数使用上面创建的变量。
使用 HttpClient 对象设置客户端的安全协议和标头信息。请务必将订阅密钥添加到 Ocp-Apim-Subscription-Key 标头中。然后，为请求创建 StringContent 对象。

通过 PutAsync() 发送请求。如果请求成功，则返回响应。

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

发送墨迹识别请求

创建名为 recognizeInk() 的新函数。通过终结点、订阅密钥、API 的 URL 以及数字墨迹笔划数据调用 Request() 函数，构造请求并将其发送。

反序列化 JSON 对象，并将其写入控制台。

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

加载数字墨迹数据

创建一个名为 LoadJson() 的函数，以便加载墨迹数据 JSON 文件。使用 StreamReader 和 JsonTextReader 创建 JObject 并将其返回。

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

发送 API 请求

在应用程序的 main 方法中，使用上面创建的函数加载 JSON 数据。

调用上面创建的 recognizeInk() 函数。使用 System.Console.ReadKey()，在运行应用程序后让控制台窗口保持打开状态。

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

运行应用程序并查看响应

运行应用程序。成功的响应以 JSON 格式返回。也可在 GitHub 上找到 JSON 响应。

后续步骤

REST API 参考

若要了解墨迹识别 API 在数字墨迹应用中的工作原理，请查看 GitHub 上的以下示例应用程序：