メインコンテンツまでスキップ

ワンタイム APPKEY

APPKEYの安全な取り扱い​

APPKEY は、アプリケーションが AmiVoice API を利用する際の「サービス認証キー文字列」であり、漏洩すると悪用される恐れがあります。APPKEY をアプリケーションに埋め込むと、悪意のある第三者によってアプリケーションから APPKEY を取り出される可能性があります。一般に、ご自身が所有している APPKEY をアプリケーションの利用者のマシンには送付しないでください。代わりに流出しても影響範囲を最小限にできるように有効期限付きのワンタイム APPKEY を利用してください。

注記
  • ワンタイム APPKEY は、マイページに記載された APPKEY と同様の機能を持つ「サービス認証キー文字列」ですが、「発行日時と有効時間」にもとづいて「有効期限日時」が設定されている点が異なります。 また、接続元のIPアドレスの制限を設けることができます。
  • ワンタイム APPKEY に発行数の上限はありません。
注意
  • 特に Web アプリケーションの場合、HTML や JavaScript に APPKEY を記述すると、Web サイトの利用者から閲覧が可能ですので避けてください。
  • APPKEY をアプリケーションに埋め込むことが避けられない場合は、APPKEY を難読化、暗号化してください。難読化、暗号化することでアプリケーションから APPKEY を取り出すことが難しくなります。
  • APPKEY は変更出来ません。変更するには退会ののち新たにアカウントを作成する必要があります。
  • 無期限で発行したワンタイム APPKEY はマイページの APPKEY と同様に変更や無効化が出来ないため発行の際には十分な検討の上ご利用ください。

ワンタイム APPKEY を使う​

ワンタイム APPKEY を使う場合、以下のような実装方法が考えられます。

  1. アプリケーション利用者を何らかの方法で認証する
  2. 認証に成功した後、サーバ側で有効期限を設定したワンタイム APPKEY を発行してアプリケーションに送信する
  3. アプリケーションではワンタイム APPKEY を利用して AmiVoice API を利用する

以下に、ワンタイム APPKEY 発行 API の使い方を説明します。

リクエスト​

ワンタイム APPKEY 発行 API を利用するためには、サービス ID（クエリパラメータ名は sid）とサービスパスワード（spw）の設定が必要です。 マイページの「接続情報」の「共通接続情報」に記載されている[サービス ID]と[サービスパスワード]を設定してください。

注記

サービスパスワードとマイページへのログイン用のパスワードは異なります。

有効時間（クエリパラメータ名は epi）は任意に設定できます。epi に数値で設定する場合はミリ秒単位になります。その他の設定方法はリファレンスを参照してください。epi を省略した場合はデフォルト値として 30000（30 秒）が設定されます。ワンタイム APPKEY を発行してから、実際に AmiVoice API のリクエストを送信するまでの時間を想定して設定してください。ipaにAPPKEYを利用できるIPアドレスを指定することができます。

curl コマンドを使って、ワンタイム APPKEY を発行してみます。

例1

IPアドレス 203.0.113.253 からのアクセスのみに制限し、有効期限を発行から 30 秒後に設定します。

curl -X POST https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={サービスID} \
     -d spw={サービスパスワード} \
     -d epi=30000 \
     -d ipa=203.0.113.253

例2

IPアドレスを範囲で指定して許可したい場合、CIDRで指定できます。

curl -X POST https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={サービスID} \
     -d spw={サービスパスワード} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24

例3

IPアドレスや、その範囲は、,で区切って複数指定もできます。

curl -X POST https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={サービスID} \
     -d spw={サービスパスワード} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24,198.51.100.0/24

レスポンス​

レスポンスはプレーンテキストで、ワンタイム APPKEY を返します。そのまま、リクエストパラメータのauthorization キーとして設定できます。

エラー時の対処方法​

ワンタイム APPKEY による接続認証が失敗するケース​

遅延（期限切れ）による認証エラー​

authorization キーによる認証要求を受け取るタイミングが、ワンタイム APPKEY に設定された有効期限日時を過ぎている場合、音声認識サービスは以下のようなエラーを返しますので、改めてワンタイム APPKEY を取得してやり直してください。

HTTP インタフェース のエラーレスポンス

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket インタフェース のエラーレスポンス

s service authorization has expired: 20XX/XX/XX XX:XX:XX.000 +0000 (-21s)

s 応答に含まれる 20XX/XX/XX XX:XX:XX.000 がワンタイム APPKEY の有効期限日時、-21s が有効期限からの遅延時間です。

s コマンド応答パケットではエラーが発生していない場合でも、最初の p パケット送信までに時間が経過して有効期限日時を過ぎてしまった場合には、最初の p パケット送信直後に以下のエラーレスポンスが返ります。

p can’t feed audio data to recognizer server

p パケット送信開始の成功後は、途中で有効期限切れになることはありません。

不正 ID による認証エラー​

ワンタイム APPKEY 発行 API に指定するサービス ID・サービスパスワードが誤っている場合でも、ワンタイム APPKEY は発行されます。AmiVoice API のリクエスト時に、誤ったサービス ID、パスワードで作成された不正なワンタイム APPKEY を指定すると、以下のような認証エラーを返します。

HTTP インタフェース のエラーレスポンス

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket インタフェース のエラーレスポンス

s can't verify service authorization

この場合は、ワンタイム APPKEY 発行依頼時に指定するサービス ID（sid）、サービスパスワード（spw）が正しい値になっているかを確認してください。

ワンタイム APPKEY 発行 API の詳細については、リファレンスのワンタイム APPKEY 発行 APIを参照してください。

非同期 HTTP インタフェース でワンタイム APPKEY を使う場合​

非同期 HTTP インタフェース でワンタイム APPKEY を利用する場合は、有効期限を十分に長くしてください。通常、音声認識開始までに数分の時間がかかります。また、混雑時にはごくまれにいったん停止してから、再開することもあり、認識途中でも認証が必要になることがあります。