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

ワンタイムAppKey

AppKey の機密性について

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

note

ワンタイム AppKey は、マイページに記載された AppKey と同様の機能を持つ「サービス認証キー文字列」ですが、「発行日時と有効時間」にもとづいて「有効期限日時」が設定されている点が異なります。

caution
  • 特に Web アプリケーションの場合、HTML や JavaScript に AppKey を記述すると、Web サイトの利用者から閲覧が可能ですので避けてください。
  • AppKey をアプリケーションに埋め込むことが避けられない場合は、AppKey を難読化、暗号化してください。難読化、暗号化することでアプリケーションから AppKey を取り出すことが難しくなります。

ワンタイム AppKey を使う

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

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

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

リクエスト

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

note

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

有効時間(クエリパラメータ名は epi)は任意に設定できます。epi はミリ秒単位です。epi を省略した場合はデフォルト値として 30000(30 秒)が設定されます。ワンタイム AppKey を発行してから、実際に AmiVoice API のリクエストを送信するまでの時間を想定して設定してください。

curl コマンドを使って、有効期限が発行したときから 30 秒後に設定されたワンタイム AppKey を発行するには以下のようにします。

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

レスポンス

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

注意

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

遅延(期限切れ)による認証エラー

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

HTTP 音声認識 API のエラーレスポンス

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

WebSocket 音声認識 API のエラーレスポンス

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 音声認識 API のエラーレスポンス

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

WebSocket 音声認識 API のエラーレスポンス

s can't verify service authorization

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

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