快速入門：使用筆跡辨識器 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();
    }  
}

載入數位筆跡資料並傳送要求

在您應用程式的主要方法中，讀入 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 上的下列應用程式範例：

共用方式為