自動音声認識(ASR)アノテーションセットのコンテンツ取得API
Note: Submit your skill and see it come to life.
自動音声認識(ASR)アノテーションセットのコンテンツ取得API
このAPIを呼び出すと、アノテーションセットのコンテンツをtext/csvまたはapplication/json形式でダウンロードできます。
HTTPメソッドとパス
GET v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}/annotations?maxResults={maxResults}&nextToken={nextToken}
アトリビュート | 型 | 説明 | 必須 |
---|---|---|---|
skillId | 文字列 | URIパスに含むスキルIDです。 | ◯ |
annotationSetId | 文字列 | URIパスに含むアノテーションセットIDです。 | ◯ |
maxResults | 整数 | 返す結果の最大数を示すクエリパラメーター。デフォルトは1000です。サーバーは、指定されたmaxResults値よりも少ない結果の数に制限することがあります。 | ✕ |
nextToken | 文字列 | 継続トークンを指定するクエリパラメーターです。 | ✕ |
注:
maxResults
クエリパラメーターは、Accept
ヘッダーの値がapplication/json
である場合にのみ適用されます。Accept
ヘッダーの値がtext/csv
の場合、クエリパラメーターとしてmaxResults
を指定しても、アノテーションセットの結果は分割されません。分割されていない結果を返すことで、CSVデータをスプレッドシートアプリケーションに簡単にインポートできます。リクエスト
リクエストヘッダー
Accept: [text/csv, application/json]
アトリビュート | 型 | 説明 | 必須 |
---|---|---|---|
Accept | 文字列 |
クライアントが受け付ける応答のコンテンツタイプを示すリクエストヘッダー。指定できる値は次のとおりです。
|
◯ |
リクエスト本文
なし
応答
HTTPステータス
HTTP 200 OK
応答ヘッダー
Content-Type: [text/csv, application/json]
応答本文
Content-Type: application/json
{
"paginationContext": {
"nextToken": string
},
"annotations": [{
"uploadId": string,
"filePathInUpload": string,
"evaluationWeight": integer,
"expectedTranscription": string,
"audioAsset": {
"downloadUrl": string,
"expiryTime": string
}
}]
}
アトリビュート | 型 | 説明 | 必須 |
---|---|---|---|
annotations[i] | オブジェクト | アノテーションオブジェクト。有効な値はuploadId、filePathInUpload、evaluationWeight、expectedTranscription、audioAssetです。 | ◯ |
audioAsset | オブジェクト | オーディオのダウンロードに関する情報を含むオブジェクト。 | ◯ |
audioAsset.downloadUrl | 文字列 | 音声ファイルをダウンロードするための署名付きダウンロードURL。 | ◯ |
audioAsset.expiryTime | 文字列 | ダウンロードURLの有効期限のタイムスタンプ(ISO 8601形式)。 | ◯ |
paginationContext | オブジェクト | ページ分割情報を含むオブジェクト。これが存在する場合、応答のアノテーションセットは不完全です。存在しない場合、すべてのアノテーションセットが既に返されています。 | ✕ |
paginationContext.nextToken | 文字列 | 次のリクエストでnextToken の値を継続トークン(nextToken クエリパラメーター)に指定して、アノテーションの次のページを取得します。 |
✕ |
Content-Type: text/csv
uploadId,filePathInUpload,evaluationWeight,expectedTranscription,audioAssetDownloadUrl,audioAssetDownloadUrlExpiryTime
string,string,integer,string,string,string
アトリビュート | 型 | 説明 | 必須 |
---|---|---|---|
uploadId | 文字列 | Catalog APIを使用してアップロードを作成したときに返されるアップロードID。 | ◯ |
filePathInUpload | 文字列 | アップロードされたzipファイル内のファイルパス。たとえば、folderという名前のフォルダと、そのフォルダにaudio.mp3という名前の音声ファイルが含まれているzipファイルがあるとします。ファイルのパスは、folder/audio.mp3です。ディレクトリを連結するには、スラッシュ(/)を使用します。 | ◯ |
evaluationWeight | 整数 | 評価におけるテスト項目の重み。この値は、OVERALL_ERROR_RATEなどのメトリクスを計算するときに使用します。許容される値は、1~1000です。 | ◯ |
expectedTranscription | 文字列 | 入力音声の文字起こしの期待結果です。文字列の許容可能な長さは、1~500のUnicode文字です。 | ◯ |
audioAssetDownloadUrl | 文字列 | 音声をダウンロードするためのURL。 | ◯ |
audioAssetDownloadUrlExpiryTime | 文字列 | ダウンロードURLの有効期限のタイムスタンプ(ISO-8601形式)。 | ◯ |
エラー応答
このセクションでは、リクエスト固有のエラーについて説明します。すべてのASR APIに適用されるエラーのリファレンスについては、自動音声認識(ASR)APIエラーリファレンスを参照してください。
HTTPステータスコード | エラーコード | シナリオ |
---|---|---|
404 Not Found |
RESOURCE_NOT_FOUND |
要求されたスキルが見つかりません。 |
要求されたアノテーションセットが見つかりません。 |
||
400 Bad Request |
INVALID_REQUEST_PARAMETER |
AnnotationSetIdの形式が正しくありません。 |
nextTokenの値が無効です。 |
||
INAVLID_INTEGER_VALUE | maxResultsの値が許容範囲外です。 | |
MISSING_REQUIRED_PROPERTY |
Acceptヘッダーがありません。 |
|
INVALID_ENUM_VALUE |
Acceptヘッダーの値が無効です。 |
|
PARAMETER_EXPIRED | nextTokenの有効期限が切れています。 | |
500 Internal Server Error |
INTERNAL_SERVER_ERROR |
内部サーバエラーのため、リクエストが失敗しました。 |
例
サンプルリクエスト | 応答の例 |
---|---|
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations HTTP/1.1 Accept: text/csv
|
HTTP 200 OK Content-Type: text/csv filePathInUpload,uploadId,evaluationWeight,expectedTranscription,audioAssetDownloadUrl,audioAssetDownloadUrlExpiryTime hello_world.mp3,amazn.catalog.upid.12341234,5,alexa hello world, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ ask say hello.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA,2020-04-013 13:23PM TZ ask say hello.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ something.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ |
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations HTTP/1.1 Accept: application/json |
HTTP 200 OK Content-Type: application/json { "annotations":[ { "uploadId": "1234-12314-12314", "filePathInUpload":"hello_world.mp3", "evaluationWeight":5, "expectedTranscription":"alexa hello world", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-12 10:23:32AM" } }, { "uploadId":"1234-12314-12315", "filePathInUpload":"ask say hello.wav", "evaluationWeight":10, "expectedTranscription":"ask hello world skill say hello", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-12 10:23:32AM" } }, { "uploadId": "1234-12314-12348", "filePathInUpload":"ask say hello.wav", "evaluationWeight":10, "expectedTranscription":"ask hello world skill say hello", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-12 10:23:32AM" } }, { "uploadId": "1234-12314-12348", "filePathInUpload":"something.wav", "evaluationWeight":10, "expectedTranscription":"ask hello world skill say hello", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-12 10:23:32AM" } } ] } |
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations?maxResults=1 HTTP/1.1 Accept: application/json |
HTTP 200 OK Content-Type: application/json { "paginationContext": { "nextToken": "1234" }, "annotations":[ { "uploadId": "1234-12314-12314", "filePathInUpload":"hello_world.mp3", "evaluationWeight":5, "expectedTranscription":"alexa hello world", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-12 10:23:32AM" } } ] } |
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations?maxResults=1?nextToken=1234 HTTP/1.1 Accept: application/json |
HTTP 200 OK Content-Type: application/json { "paginationContext": { "nextToken": "2345" }, "annotations":[ { "uploadId": "1234-12314-12315", "filePathInUpload":"hello_alexa.mp3", "evaluationWeight":5, "expectedTranscription":"alexa hello world", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-13 10:23:32AM" } } ] } |
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations HTTP/1.1 Accept: application/json |
HTTP 400 Bad Request Content-Type: application/json { "message": "Annotation set not found", "violations": [{ "message": "Annotation set identified by 1234-1234-12341234 cannot be found", "code": "RESOURCE_NOT_FOUND" }] } |