Amazon Transcribe
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

通过 WebSockets 使用 Amazon Transcribe 流式处理

当您使用 WebSocket 协议流式传输音频时,Amazon Transcribe 会实时转录音频流。您可以使用事件流编码方式对音频进行编码,Amazon Transcribe 通过也使用事件流编码方式进行编码的 JSON 结构进行响应。有关更多信息,请参阅 事件流编码。您可以使用此部分中的信息,使用所选 WebSocket 库创建应用程序。

将 WebSocket 请求的策略添加到您的 IAM 角色

要使用 WebSocket 协议调用 Amazon Transcribe,您需要将以下策略附加到发出请求的 AWS Identity and Access Management (IAM) 角色。

{ "Version": "2012-10-17", "Statement": [ { "Sid": "transcribestreaming", "Effect": "Allow", "Action": "transcribe:StartStreamTranscriptionWebSocket", "Resource": "*" } ] }

创建预签名 URL

为 WebSocket 请求构造一个 URL,该请求中包含在应用程序和 Amazon Transcribe 之间建立通信所需的信息。WebSocket 流式处理使用 Amazon 签名版本 4 流程处理签名请求。对请求签名有助于验证请求者的身份并保护传输中的音频数据。它还可以防止潜在的重放攻击。有关签名版本 4 的更多信息,请参阅 Amazon Web Services 一般参考 中的签署 AWS API 请求

URL 采用以下格式。为了便于阅读,已增加了换行符。

GET https://transcribestreaming.region.amazonaws.com:8443/stream-transcription-websocket ?language-code=languageCode &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=Signature Version 4 credential scope &X-Amz-Date=date &X-Amz-Expires=time in seconds until expiration &X-Amz-Security-Token=security-token &X-Amz-Signature=Signature Version 4 signature &X-Amz-SignedHeaders=host &media-encoding=mediaEncoding &sample-rate=mediaSampleRateHertz &session-id=sessionId &vocabulary-name=vocabularyName

为 URL 参数使用以下值:

  • language-code – 输入音频的语言代码。有效值为 en-GB, en-US, es-US, fr-CA,fr-FR

  • media-encoding – 用于输入音频的编码。唯一有效值为 pcm

  • sample-rate – 输入音频的采样率,以 Hz 为单位。我们建议您对低质量音频使用 8000 Hz,对高质量音频使用 16000 Hz。采样率必须与音频文件中的采样率匹配。

  • sessionId – 可选。转录会话的标识符。如果您未提供会话 ID,Amazon Transcribe 为您生成一个并在响应中返回它。

  • vocabulary-name – 可选。处理转录作业时使用的词汇表(如果有)的名称。

剩余参数是签名版本 4 参数:

  • X-Amz-Algorithm – 您在签名过程中使用的算法。唯一有效值为 AWS4-HMAC-SHA256

  • X-Amz-Credential – 以斜杠(“/”)分隔的字符串,它通过将您的访问密钥 ID 和凭证范围组件串联起来而形成。凭证范围包括采用 YYYYMMDD 格式的日期、AWS 区域、服务名称和特殊的终止字符串 (aws4_request)。

  • X-Amz-Date – 创建签名的日期和时间。按照 Amazon Web Services 一般参考处理签名版本 4 中的日期中的说明生成日期和时间。

  • X-Amz-Expires – 凭证到期之前的时间长度(以秒为单位)。最大值为 300 秒(5 分钟)。

  • X-Amz-Security-Token – 可选。临时凭证的签名版本 4 令牌。如果您指定此参数,则将其包含在规范请求中。有关更多信息,请参阅 AWS Identity and Access Management 用户指南 中的请求临时安全凭证

  • X-Amz-Signature – 您为请求生成的签名版本 4 签名。

  • X-Amz-SignedHeaders – 在为请求创建签名时签名的标头。唯一有效值为 host

要构造请求的 URL 并创建签名版本 4 签名,请使用以下步骤。这些示例是伪代码。

任务 1:创建规范请求

创建一个字符串,其中包含来自标准格式的请求的信息。这可确保 AWS 在收到请求时,计算出的签名与您在任务 3 中计算出的签名相同。有关更多信息,请参阅 Amazon Web Services 一般参考 中的针对签名版本 4 创建规范请求

  1. 为您应用程序中的请求定义变量。

    # HTTP verb method = "GET" # Service name service = "transcribe" # AWS Region region = "AWS Region" # Amazon Transcribe streaming endpoint endpoint = "https://transcribestreaming.region.amazonaws.com:8443" # Host host = "transcribestreaming.region.amazonaws.com:8443" # Date and time of request amz-date = YYYMMDD'T'HHMMSS'Z' # Date without time for credential scope datestamp = YYYYMMDD
  2. 创建规范 URI。规范 URI 是域与查询字符串之间的 URI 部分。

    canonical_uri = "/stream-transcription-websocket"
  3. 创建规范标头和签名标头。请注意规范标头尾部的 "\n"

    canonical_headers = "host:" + host + "\n" signed_headers = "host"
  4. 将算法与哈希算法匹配。您必须使用 SHA-256。

    algorithm = "AWS4-HMAC-SHA256"
  5. 创建凭证范围,该范围将派生密钥范围限定为发出请求的日期以及将请求发送到的区域和服务。

    credential_scope = datestamp + "/" + region + "/" + service + "/" + "aws4_request"
  6. 创建规范查询字符串。查询字符串值必须是 URL 编码,并且按名称排序。

    canonical_querystring = "X-Amz-Algorithm=" + algorithm canonical_querystring += "&X-Amz-Credentials="+ access key + "/" + credential_scope canonical_querystring += "&X-Amz-Date=" + amz_date canonical_querystring += "&X-Amz-Expires=300" canonical_querystring += "&X-Amz-Security-Token=" + token canonical_querystring += "&X-Amz-SignedHeaders=" + signed_headers canonical_querystring += "&language-code=en-US&media-encoding=pcm&sample-rate=16000"
  7. 创建负载的哈希。对于 GET 请求,负载为空字符串。

    payload_hash = HashSHA256(("").Encode("utf-8")).HexDigest()
  8. 组合所有元素以创建规范请求。

    canonical_request = method + '\n' + canonical_uri + '\n' + canonical_querystring + '\n' + canonical_headers + '\n' + signed_headers + '\n' + payload_hash

任务 2:创建待签字符串

待签字符串包含您的请求的元信息。在计算请求签名时,您可以使用该字符串登录下一步。有关更多信息,请参阅 Amazon Web Services 一般参考 中的创建签名版本 4 的待签字符串

  • 创建字符串。

    string_to_sign=algorithm + "\n" + amz_date + "\n" + credential_scope + "\n" + HashSHA256(canonical_request.Encode("utf-8").HexDigest()

任务 3:计算签名

您可以从您的 AWS 秘密访问密钥派生签名密钥。为了实现更高程度的保护,派生密钥特定于日期、服务和 AWS 区域。您可以使用派生密钥签名请求。有关更多信息,请参阅 Amazon Web Services 一般参考 中的创建 AWS 签名版本 4 的签名

该代码假定您实施了函数 GetSignatureKey 来派生签名密钥。有关更多信息和示例函数,请参阅 Amazon Web Services 一般参考 中的说明如何为签名版本 4 派生签名密钥的示例

函数 HMAC(key, data) 表示以二进制格式返回结果的 HMAC-SHA256 函数。

  • 创建签名密钥,然后为待签字符串签名。

    #Create the signing key. signing_key = GetSignatureKey(secret_key, datestamp, region, service) # Sign the string_to_sign using the signing key signature = HMAC.new(signing_key, (string_to_sign).Encode("utf-8"), Sha256()).HexDigest

任务 4:将签名信息添加到请求中并创建请求 URL

在计算签名之后,将它添加到查询字符串。有关更多信息,请参阅 Amazon Web Services 一般参考 中的将签名添加到 HTTP 请求

  1. 将身份验证信息添加到查询字符串。

    canonical_querystring += "&X-Amz-Signature=" + signature
  2. 创建请求的 URL。

    request_url = endpoint + canonical_uri + "?" + canonical_querystring

您可将请求 URL 与 WebSocket 库一起使用,以向 Amazon Transcribe 服务发出请求。

包括 WebSocket 请求标头

对 Amazon Transcribe 的请求必须包含以下标头。通常,这些标头由您的 WebSocket 客户端库管理。

Host: transcribestreaming.region.amazonaws.com:8443 Connection: Upgrade Upgrade: websocket Origin: request source Sec-WebSocket-Version: 13 Sec-WebSocket-Key: random key

为标头使用以下值:

  • Connection – 始终为 Upgrade

  • Upgrade – 始终为 websocket

  • Origin – WebSocket 客户端的 URI。

  • Sec-WebSocket-Version – 要使用的 WebSocket 协议的版本。

  • Sec-WebSocket-Key – Base-64 编码的随机生成的字符串,用于标识请求。

处理 WebSocket 升级响应

Amazon Transcribe 收到您的 WebSocket 请求时,它会使用 WebSocket 升级响应做出响应。通常,您的 WebSocket 库管理此响应,并设置套接字以与 Amazon Transcribe 进行通信。

以下是来自 Amazon Transcribe 的响应。为了便于阅读,已经向 websocket-location 标头添加了换行符。

HTTP/1.1 101 Web Socket Protocol Handshake Connection: upgrade Upgrade: websocket websocket-origin: https://transcribestreaming.region.amazonaws.com:8443 websocket-location: transcribestreaming.region.amazonaws.com:8443/stream-transcription-websocket? X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIDEXAMPLE%2F20190117%2Fregion%2Ftranscribe%2Faws4_request &X-Amz-Date=date and time &X-Amz-Expires=expiration length &X-Amz-SignedHeaders=host &language-code=language code &media-encoding=media encoding &sample-rate=media sample rate &X-Amz-Signature=signature x-amzn-RequestId: RequestId x-amzn-SessionId: SessionId Strict-Transport-Security: max-age=31536000 sec-websocket-accept: token

响应具有以下值:

  • Connection – 始终为 Upgrade

  • Upgrade – 始终为 websocket

  • websocket-origin – 响应请求的 WebSocket 服务器的 URI。

  • websocket-location – 发送到服务器的请求 URI 的内容。有关内容的说明,请参阅 创建预签名 URL

  • x-amzn-RequestId – 请求的标识符。

  • x-amzn-SessionId – 转录会话的标识符。

  • Strict-Transport-Security – 一个标头,通知浏览器仅使用 HTTPS 访问终端节点。

  • sec-websocket-accept – 在请求中发送的 Sec-WebSocket-Key 标头的哈希值。

发出 WebSocket 流式处理请求

建立 WebSocket 连接后,客户端可以开始发送一系列二进制 WebSocket 帧。每个帧包含一个以事件流编码方式进行编码的数据帧。有关更多信息,请参阅 事件流编码

每个数据帧包含三个标头以及原始音频字节区块。下表列出并描述了标头。

标头名称字节长度 标头名称(字符串) 标头值类型 值字符串字节长度 值字符串 (UTF-8)
13 :content-type 7 24 application/octet-stream
11 :event-type 7 10 AudioEvent
13 :message-type 7 5 event

要结束音频数据流,请在 event-stream-encoded 消息中发送空音频区块。

处理 WebSocket 流式处理响应

响应包含负载中的 event-stream-encoded 的原始字节。它包含标准前导信息和以下标头。

标头名称字节长度 标头名称(字符串) 标头值类型 值字符串字节长度 值字符串 (UTF-8)
13 :content-type 7 24 application/octet-stream
11 :event-type 7 15 TranscriptEvent
13 :message-type 7 5 event

解码二进制响应时,最终会得到带有转录结果的 JSON 结构。有关 JSON 响应的示例,请参阅流式转录

处理 WebSocket 流式处理错误

如果在处理您的请求时发生异常,Amazon Transcribe 使用包含事件流编码响应的终端 WebSocket 帧进行响应。该响应具有下表中描述的标头,以及包含描述性错误消息的响应正文。发送异常响应后,Amazon Transcribe 会发送一个关闭帧。

标头名称字节长度 标头名称(字符串) 标头值类型 值字符串字节长度 值字符串 (UTF-8)
13 :content-type 7 24 application/octet-stream
15 :exception-type 7 变化 各种编号,请参阅下文
13 :message-type 7 9 exception

exception-type 标头包含以下值之一。

  • BadRequestException – 创建流时发生客户端错误,或者流式处理数据中发生错误。确保您的客户端已准备好接受数据,然后重试请求。

  • InternalFailureException – Amazon Transcribe 在与客户端握手期间遇到问题。请再次尝试您的请求。

  • LimitExceededException – 客户端超出了并发流限制。有关更多信息,请参阅 Amazon Web Services 一般参考 中的 Amazon Transcribe 限制。减少要转录的流的数量。

  • UnrecognizedClientException – 使用不正确的访问密钥或私有密钥对 WebSocket 升级请求进行了签名。请确保您正确创建了访问密钥,然后重试请求。

此外,Amazon Transcribe 还可以返回任何常见服务错误。有关错误列表,请参阅常见错误