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

注意

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

新しいアプリケーションを作成する

1. 普段使用している 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;
   

2. サブスクリプション キー、エンドポイント、および 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";
   

要求を送信する関数を作成する

1. 上記で作成した変数を取る sendRequest() という新しい関数を作成します。 次に、以下の手順のようにします。

2. API に要求を送信できる CloseableHttpClient オブジェクトを作成します。 エンドポイントと Ink Recognizer URL を組み合わせて、HttpPut 要求オブジェクトに要求を送信します。

3. 要求の setHeader() 関数を使用して、Content-Type ヘッダーを application/json に設定し、サブスクリプション キーを Ocp-Apim-Subscription-Key ヘッダーに追加します。

4. 送信するデータに対して要求の setEntity() 関数を使用します。

5. クライアントの execute() 関数を使用して、要求を送信し、それを CloseableHttpResponse オブジェクトに格納します。

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

デジタル インク データを読み込み、要求を送信する

1. アプリケーションの main メソッドで、要求に追加されるデータを含む JSON ファイルを読み取ります。

2. 上記で作成したインク認識関数を呼び出します。

   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 上の次のサンプル アプリケーションを参照してください。

• C# およびユニバーサル Windows プラットフォーム (UWP)
• C# および Windows Presentation Foundation (WPF)
• JavaScript Web ブラウザー アプリ
• Java および Android モバイル アプリ
• Swift および iOS モバイル アプリ