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

项目
08/24/2020

注意

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

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

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

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

手写文本图像

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

先决条件

Java™ 开发工具包 (JDK) 7 或更高版本。
将这些库从 Maven 存储库导入
- 以 Java 编写的 JSON 包
- Apache HttpClient 包
可以在 GitHub 上找到此快速入门的示例墨迹笔划数据。

创建“墨迹识别器”资源

注意

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

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

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

创建两个环境变量：

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

创建新应用程序

在你最喜欢的 IDE 或编辑器中新建一个 Java 项目，并导入以下库。

import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import com.fasterxml.jackson.core.JsonParseException;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

为订阅密钥、终结点和 JSON 文件创建变量。稍后会将终结点追加到墨迹识别器 URI。

// Add your Azure Ink Recognition subscription key to your environment variables.
private static final String subscriptionKey = System.getenv("INK_RECOGNITION_SUBSCRIPTION_KEY");

// Add your Azure Ink Recognition endpoint to your environment variables.
public static final String rootUrl = System.getenv("INK_RECOGNITION_ENDPOINT");
public static final String inkRecognitionUrl = "/inkrecognizer/v1.0-preview/recognize";
// Replace the dataPath string with a path to the JSON formatted ink stroke data file.
private static final String dataPath = "PATH_TO_INK_STROKE_DATA";

创建用于发送请求的函数

创建名为 sendRequest() 的新函数，该函数使用上面创建的变量。然后，执行以下步骤。
创建可以向 API 发送请求的 CloseableHttpClient 对象。通过组合使用终结点和墨迹识别器 URL，将请求发送给 HttpPut 请求对象。
使用请求的 setHeader() 函数将 Content-Type 标头设置为 application/json，然后将订阅密钥添加到 Ocp-Apim-Subscription-Key 标头。
使用请求的 setEntity() 函数来设置要发送的数据。
使用客户端的 execute() 函数来发送请求，并将其保存到 CloseableHttpResponse 对象。

创建 HttpEntity 对象，用于存储响应内容。使用 getEntity() 获取内容。如果响应不为空，请将其返回。

static String sendRequest(String endpoint, String apiAddress, String subscriptionKey, String requestData) {
    try (CloseableHttpClient client = HttpClients.createDefault()) {
        HttpPut request = new HttpPut(endpoint + apiAddress);
        // Request headers.
        request.setHeader("Content-Type", "application/json");
        request.setHeader("Ocp-Apim-Subscription-Key", subscriptionKey);
        request.setEntity(new StringEntity(requestData));
        try (CloseableHttpResponse response = client.execute(request)) {
            HttpEntity respEntity = response.getEntity();
            if (respEntity != null) {
                return EntityUtils.toString(respEntity, "utf-8");
            }
        } catch (Exception respEx) {
            respEx.printStackTrace();
        }
    } catch (IOException ex) {
        System.err.println("Exception on Anomaly Detector: " + ex.getMessage());
        ex.printStackTrace();
    }
    return null;
}

发送墨迹识别请求

创建名为 recognizeInk() 的方法，用于识别墨迹笔划数据。调用在上面使用终结点、URL、订阅密钥和 JSON 数据创建的 sendRequest() 方法。获取结果，并将其输出到控制台。

static void recognizeInk(String requestData) {
    System.out.println("Sending an Ink recognition request.");

    String result = sendRequest(rootUrl, inkRecognitionUrl, subscriptionKey, requestData);
    
    // Pretty-print the JSON result
    try {
        ObjectMapper objectMapper = new ObjectMapper();
        Map<String, Object> response = objectMapper.readValue(result, HashMap.class);
        System.out.println(objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(response));
    } catch (JsonParseException e) {
        e.printStackTrace();
    } catch (JsonMappingException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }  
}

加载数字墨迹数据并发送请求

在应用程序的 main 方法中读入 JSON 文件，其中包含将要添加到请求中的数据。

调用上面创建的墨迹识别函数。

public static void main(String[] args) throws Exception {

    String requestData = new String(Files.readAllBytes(Paths.get(dataPath)), "utf-8");
    recognizeInk(requestData);
}

运行应用程序并查看响应

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

后续步骤

REST API 参考

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

通过