使用モデル

サービスの非同期 HTTP インターフェースを操作する際は、ジョブのステータスを確認したり、結果を受信したりするために、以下の方法を選択できます。

• コールバック通知を使用する場合:
  1. POST /v1/register_callback メソッドを呼び出して、コールバック URL をサービスに登録します。 この URL に送信するコールバックの認証およびデータ保全性を実現するために、オプションでユーザー指定の秘密ストリングを指定できます。
  2. ジョブのステータス変更時にサービスが通知を送信する宛先として登録済みのコールバック URL を指定して、POST /v1/recognitions メソッドを呼び出します。 通知対象のイベントのリストを指定してください。 デフォルトでは、サービスはジョブの開始時、ジョブの完了時、およびエラーが発生した場合に通知を送信します。 完了の通知に要求の結果も含めるように要求することもできます。 通知に結果を含めない場合は、GET /v1/recognitions/{id} メソッドを使用して結果を取得する必要があります。
• サービスをポーリングする場合:
  1. コールバック URL、イベント、ユーザー・トークンを指定せずに POST /v1/recognitions メソッドを呼び出します。
  2. 定期的に GET /v1/recognitions メソッドを呼び出して最近のジョブのステータスを確認するか、または GET /v1/recognitions/{id} メソッドを呼び出して特定のジョブのステータスを確認します。
  3. GET /v1/recognitions メソッドでジョブのステータスを確認する場合は、ジョブが完了したら、GET /v1/recognitions/{id} メソッドを呼び出してジョブの結果を取得します。

この 2 つの方法は一緒に使用できます。 コールバック URL を指定して作成したジョブでも、サービスをポーリングして、そのジョブの最新のステータスを取得することができます。 例えば、通知が到着するまでに時間がかかっている場合には、ジョブのステータスを手動で取得するとよいでしょう。 また、サービスまたはネットワークのエラーが原因で 1 つ以上の通知を見逃した可能性がある場合にも、ステータスを確認できます。

コールバック URL の登録

コールバック URL を登録するには、POST /v1/register_callback メソッドを呼び出します。 コールバック URL を登録した後は、そのコールバック URL を無制限の数のジョブの通知の受信に使用できます。 登録プロセスは、4 つのステップからなります。

1. POST /v1/register_callback メソッドを呼び出してコールバック URL を渡します。 オプションで、ユーザー指定の秘密を指定することもできます。 このサービスは、認証とデータの完全性のために、鍵付きハッシュ・メッセージ認証コード（HMAC）セキュア・ハッシュ・アルゴリズム（ SHA-256 ）署名を計算するために秘密を使用する。 以下に、URL http://{user_callback_path}/results で応答するユーザー・コールバックを登録する例を記載します。 この呼び出しには、ユーザーの秘密 ThisIsMySecret を含めます。

   IBM Cloud

   curl -X POST -u "apikey:{apikey}" \
   "{url}/v1/register_callback?callback_url=http://{user_callback_path}/results&user_secret=ThisIsMySecret"
   

   IBM Cloud Pak for Data IBM Software Hub

   curl -X POST \
   --header "Authorization: Bearer {token}" \
   "{url}/v1/register_callback?callback_url=http://{user_callback_path}/results&user_secret=ThisIsMySecret"
   

2. コールバック URL がまだ登録されていない場合、サービスは URL を検証する (許可リストに登録する) ために、GET 要求をコールバック URL に送信します。 要求の challenge_string クエリー・パラメーターにランダムな英数字のチャレンジ・ストリングを指定して渡します。 この要求の Accept ヘッダーには、必要な応答タイプとして text/plain が指定されています。

   register_callback メソッドへの呼び出しにユーザーシークレットが含まれてい る場合、サービスからの GET リクエストは、チャレンジ 文字列の HMAC-SHA256 署名を指定する X-Callback-Signature ヘッダーも 含む。 この署名は、サービスがユーザーの秘密を鍵として使用して算出したものです。

   GET http://{user_callback_path}/results?challenge_string=n9ArPGMQ36Hiu7QC
   header: X-Callback-Signature {HMAC-SHA256_signature}
   

3. サービスからの GET 要求に対し、ユーザーがステータス・コード 200 の応答を返します。 応答に、サービスが送信したチャレンジ・ストリングを組み込みます。 このストリングをプレーン・テキストとして応答の本体に組み込み、Content-Type 応答ヘッダーを text/plain に設定します。

   最初の POST リクエストにユーザーシークレットが含まれていた場合、そのシークレットをキーと してチャレンジ文字列の HMAC-SHA256 署名を計算することができる。 サービスから GET 要求が送信された場合、計算した署名は、X-Callback-Signature ヘッダーで指定された値と一致します。

   response code: 200 OK
   body: n9ArPGMQ36Hiu7QC
   

4. サービスは、送信した GET要求に対する応答の本体でチャレンジ・ストリングが返されているかどうかをチェックします。 返されている場合、サービスはコールバック URL を許可リストに登録し、元の POST 要求に対してステータス・コード 201 の応答を返します。 応答本体に含まれる JSON オブジェクトの status フィールドには値 created が指定され、url フィールドには値としてコールバック URL が指定されます。

   response code: 201 Created
   body: {
     "status": "created",
     "url": "http://{user_callback_path}/results"
   }
   

サービスが登録プロセスでコールバック URL に送信する GET 要求は 1 つだけです。 サービスは、本体にチャレンジ・ストリングが組み込まれている応答コード 200 の応答を 5 秒以内に受信する必要があります。 この応答を受信しないと、サービスは URL を許可リストに登録しません。 サービスは、代わりに、POST /v1/register_callback 要求に対する応答としてステータス・コード 400 を送信します。 コールバック URL が既に正常に許可リストに登録されていた場合、サービスは最初の POST 要求に対する応答としてステータス・コード 200 を送信します。

curl -X POST -u "apikey:{apikey}" \
"{url}/v1/unregister_callback?callback_url=http://{user_callback_path}/results"

curl -X POST \
--header "Authorization: Bearer {token}" \
"{url}/v1/unregister_callback?callback_url=http://{user_callback_path}/results"

ジョブの作成

認識ジョブを作成するには、POST /v1/recognitions メソッドを呼び出します。 ジョブのステータスと結果を調べる方法は、以下のどちらの方法を使用するか、および呼び出しでどのパラメーターを渡すかによって決まります。

• コールバック通知を使用する場合、コールバック通知の送信先 URL を指定する callback_url クエリー・パラメーターを含めます。ジョブのステータスが変わると、サービスはこの URL にコールバック通知を送信します。 オプションで、以下のクエリー・パラメーターを指定することもできます。
  • events: サブスクライブする通知イベントのリストを指定します。 デフォルトでは、サービスはジョブの開始時 (recognitions.started イベント)、ジョブの完了時 (recognitions.completed イベント)、およびエラーが発生した場合 (recognitions.failed イベント) にコールバック通知を送信します。 これらのイベントのサブセットを指定したり、recognitions.completed_with_results イベントの代わりに recognitions.completed イベントを使用してジョブ完了の通知に結果を含めたりすることもできます。
  • user_token: ジョブの各通知に含めるストリングを指定します。 無制限の数のジョブで同じコールバック URL を使用できるため、ユーザー・トークンを利用することで、異なるジョブの通知を区別できます。
• ポーリングを使用する場合、callback_url、events、および user_token の各クエリー・パラメーターを省略します。 この場合、GET /v1/recognitions または GET /v1/recognitions/{id} メソッドを使用して、ジョブのステータスを確認する必要があります。ジョブの完了時に結果を取得する場合は、後者のメソッドを使用します。

いずれの場合も、results_ttl クエリー・パラメーターを含めることで、ジョブの完了後にその結果を取得可能な状態に維持する期間 (分数) を指定できます。 新規ジョブは、それを作成するために資格情報が使用されたサービスのインスタンスによって所有されます。

POST /v1/recognitions メソッドは、非同期インターフェースに固有の上記のパラメーターに加え、WebSocket インターフェースおよび同期 HTTP インターフェースで使用するパラメーターのほとんどをサポートしています。 詳しくは、パラメーターの要約を参照してください。

{
  "id": "{job_id}",
  "event": "{recognitions_status}",
  "user_token": "{user_token}"
}

import hmac
import base64
from hashlib import sha256
# 'user_secret' and 'notification_payload' must be bytes
hashed = hmac.new(user_secret, notification_payload, sha256)
signature = base64.b64encode(hashed.digest()).decode().rstrip('\n')

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @{path}audio-file.flac \
"{url}/v1/recognitions?callback_url=http://{user_callback_path}/results&user_token=job25&timestamps=true"

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @{path}audio-file.flac \
"{url}/v1/recognitions?callback_url=http://{user_callback_path}/results&user_token=job25&timestamps=true"

{
  "created": "2016-08-17T19:15:17.926Z",
  "id": "4bd734c0-e575-21f3-de03-f932aa0468a0",
  "url": "{url}/v1/recognitions/4bd734c0-e575-21f3-de03-f932aa0468a0",
  "status": "waiting"
}

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/wav" \
--data-binary @{path}audio-file.wav \
"{url}/v1/recognitions?timestamps=true"

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/wav" \
--data-binary @{path}audio-file.wav \
"{url}/v1/recognitions?timestamps=true"

{
  "created": "2016-08-17T19:13:23.622Z",
  "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "url": "{url}/v1/recognitions/4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "status": "processing"
}

ジョブのステータスの確認と結果の取得

ジョブのステータスを確認するには、GET /v1/recognitions/{id} パス・パラメーターに対象のジョブを指定して id メソッドを呼び出します。 この応答には常に、ジョブの ID、ステータス、作成時刻、および更新時刻が組み込まれます。 ステータスが completed の場合、応答には認識要求の結果も組み込まれます。

以下の場合、ジョブの結果を取得するには、GET /v1/recognitions/{id} メソッドが唯一の手段になります。

• コールバック URL を指定せずにジョブが実行依頼された場合。
• コールバック URL を指定したが、recognitions.completed_with_results イベントを指定せずにジョブが実行依頼された場合。
• ジョブが最新の 100 件の処理待ちジョブの 1 つではない場合。 id パス・パラメーターを省略すると、最新の 100 件のジョブだけが返されます。

ただし、コールバック URL と recognitions.completed_with_results イベントが指定されていたジョブについても、このメソッドを使用して結果を取得することはできます。 ジョブの結果が取得可能な状態である間は、必要なだけ何度も結果を取得できます。 ジョブとその結果は、DELETE /v1/recognitions/{id} メソッドで結果が削除されるか、あるいはジョブの存続時間が満了するかのうち、いずれか早いほうの時点まで取得可能な状態が維持されます。 results_ttl メソッドの POST /v1/recognitions パラメーターで存続時間を別の値に設定しない限り、結果はデフォルトで 1 週間後に期限切れになります。

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"

{
  "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "created": "2016-08-17T19:13:23.622Z",
  "updated": "2016-08-17T19:13:24.434Z",
  "status": "processing"
}

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"

{
  "id": "398fcd80-330a-22ba-93ce-1a73f454dd98",
  "results": [
    {
      "result_index": 0,
      "results": [
        {
          "final": true,
          "alternatives": [
            {
              "transcript": "several tornadoes touch down as a line of severe thunderstorms swept through Colorado on Sunday ",
              "timestamps": [
                [
                  "several",
                  1,
                  1.52
                ],
                [
                  "tornadoes",
                  1.52,
                  2.15
                ],
                . . .
                [
                  "Sunday",
                  5.74,
                  6.33
                ]
              ],
              "confidence": 0.96
            }
          ]
        }
      ]
    }
  ],
  "created": "2016-08-17T19:11:04.298Z",
  "updated": "2016-08-17T19:11:16.003Z",
  "status": "completed"
}

最近のジョブのステータスの確認

最近のジョブのステータスを確認するには、GET /v1/recognitions メソッドを呼び出します。 このメソッドは、呼び出しに使用された資格情報に関連付けられている最近の 100 件の処理待ちジョブのステータスを返します。 このメソッドは、各ジョブの ID、ステータス、作成時刻、および更新時刻を返します。 コールバック URL とユーザー・トークンを指定して作成されたジョブの場合、このメソッドはジョブのユーザー・トークンも返します。

応答には以下のいずれかのステータスが含まれています。

• waiting: サービスが処理用にジョブを準備している場合。 このステータスは、すべてのジョブの初期状態です。 サービスがジョブの処理を開始できるだけのキャパシティーを確保するまで、ジョブはこのステータスのままになります。
• processing: サービスがアクティブにジョブを処理している場合。
• completed: サービスがジョブの処理を完了した場合。 ジョブにコールバック URL とイベント recognitions.completed_with_results が指定されている場合、サービスはコールバック通知で結果を送信済みです。 そうでない場合は、GET /v1/recognitions/{id} メソッドを使用して結果を取得する必要があります。
• failed: 何らかの理由でジョブが失敗した場合。

ジョブとその結果は、DELETE /v1/recognitions/{id} メソッドで結果が削除されるか、あるいはジョブの存続時間が満了するかのうち、いずれか早いほうの時点まで取得可能な状態が維持されます。

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions"

{
  "recognitions": [
    {
      "id": "4bd734c0-e575-21f3-de03-f932aa0468a0",
      "created": "2016-08-17T19:15:17.926Z",
      "updated": "2016-08-17T19:15:17.926Z",
      "status": "waiting",
      "user_token": "job25"
    },
    {
      "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
      "created": "2016-08-17T19:13:23.622Z",
      "updated": "2016-08-17T19:13:24.434Z",
      "status": "processing"
    },
    {
      "id": "398fcd80-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-08-17T19:11:04.298Z",
      "updated": "2016-08-17T19:11:16.003Z",
      "status": "completed"
    }
  ]
}

ジョブの削除

ジョブを削除するには、DELETE /v1/recognitions/{id} パス・パラメーターに対象のジョブを指定して id メソッドを使用します。 通常は、サービスからジョブの結果を取得した後でジョブを削除します。 ジョブを削除すると、そのジョブの結果を入手できなくなります。 サービスがアクティブに処理中のジョブを削除することはできません。

デフォルトでは、ジョブの有効期限が切れるまで、サービスは各ジョブの結果を維持します。 デフォルトの存続時間は 1 週間ですが、results_ttl メソッドの POST /v1/recognitions パラメーターを使用して、サービスが結果を維持する期間 (分数) を指定できます。

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"