クイックスタート:Ink Recognizer REST API および Java を使用したデジタルインクの認識

[アーティクル]
08/24/2020

注意

Ink Recognizer API は、2020 年 8 月 26 日にプレビューを終了しました。既存の Ink Recognizer リソースがある場合は、2021 年 1 月 31 日にサービスが完全に廃止されるまで、引き続き使用できます。

このクイックスタートは、デジタルインクストロークで Ink Recognizer API の使用を始めるときに使用します。この Java アプリケーションは、JSON 形式のインクストロークデータを含む API 要求を送信し、応答を取得します。

このアプリケーションは Java で記述されていますが、API はほとんどのプログラミング言語と互換性のある RESTful Web サービスです。

通常、この API はデジタルインキングアプリから呼び出します。このクイックスタートでは、JSON ファイルから次の手書きサンプルのインクストロークデータを送信します。

手書きテキストのイメージ

このクイックスタートのソースコードは、GitHub にあります。

前提条件

Java™ Development Kit(JDK) 7 以降。
Maven リポジトリから以下のライブラリをインポートします
- JSON in Java パッケージ
- Apache HttpClient パッケージ
このクイックスタートのインクストロークデータのサンプルは、GitHub にあります。

Ink Recognizer リソースを作成する

注意

2019 年 7 月 1 日より後に作成されたリソースのエンドポイントでは、次に示すカスタムサブドメイン形式を使用します。リージョンのエンドポイントの詳細および全一覧については、「Cognitive Services のカスタムサブドメイン名」を参照してください。

Azure Cognitive Services は、ユーザーがサブスクライブする Azure リソースによって表されます。 Azure portal を使用して、Ink Recognizer 用のリソースを作成します。

リソースの作成後、Azure portal でリソースを開き、 [クイックスタート] をクリックして、エンドポイントとキーを取得します。

以下の 2 つの環境変数を作成します。

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 ファイル用の変数を作成します。エンドポイントは、後で Ink Recognizer 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 オブジェクトを作成します。エンドポイントと Ink Recognizer 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 形式で返されます。 JSON 応答は GitHub でも確認できます。

次のステップ

REST API リファレンス

デジタルインキングアプリで Ink Recognition API がどのように動作するかを確認するには、GitHub 上の次のサンプルアプリケーションを参照してください。

クイック スタート:Ink Recognizer REST API および Java を使用したデジタル インクの認識