自動音声認識（ASR）アノテーションセットのコンテンツ取得API

自動音声認識（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 文字列 継続トークンを指定するクエリパラメーターです。 ✕

リクエスト

リクエストヘッダー

Accept: [text/csv, application/json]
アトリビュート 型 説明 必須
Accept 文字列

クライアントが受け付ける応答のコンテンツタイプを示すリクエストヘッダー。指定できる値は次のとおりです。

  • text/csv：アノテーションセットの内容をCSV形式で返します。
  • application/json：アノテーションセットの内容をJSON形式で返します。

 ◯

リクエスト本文

なし

応答

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" }] }