使用 WebSocket 协议建立双向连接 - Amazon Transcribe
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

使用 WebSocket 协议建立双向连接

您可以使用WebSocket 协议以建立与 Amazon Transcribe Medical 一起安全的双向连接。您可以使用事件流编码对音频流进行编码,而 Amazon Transcribe Medical 会返回 JSON Blob 形式的文本流,这些文本流也使用事件流编码进行编码。有关更多信息,请参阅 事件流编码。您可以使用此部分中的信息,使用所选 WebSocket 库创建应用程序。

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

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

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

创建预签名 URL

您需要为 WebSocket 请求构造一个 URL,该请求中包含在应用程序和 Amazon Transcribe Medical 之间建立通信所需的信息。要打开双向连接,必须使用端口 8443。WebSocket 流式处理使用 Amazon 签名版本 4 流程处理签名请求。对请求签名有助于验证请求者的身份并保护传输中的音频数据。它还可以防止潜在的重放攻击。有关签名版本 4 的更多信息,请参阅SIGNAmazonAPI 请求中的Amazon Web Services 常规参考.

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

GET https://transcribestreaming.region.amazonaws.com:8443/medical-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 &specialty=specialty &type=type

对于 TYPE(类型),如果您的使用案例涉及多个参与讨论的发言者,最好选择 CONVERSATION(会话)。一个例子是临床医生和患者之间的对话。如果您的使用案例涉及正在口述发言的单个发言者,请选择 DICTATION(口述)。一个例子是医生在接诊患者后口述医疗笔记以录入数据。

为 URL 参数使用以下值:

  • 语言代码— 输入音频的语言代码。有效值为 en-US

  • 媒体编码— 用于输入音频的编码。有效值为 pcm

  • 采样率— 以赫兹为单位的输入音频的采样率;接受 16,000 Hz 或更高的采样率。

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

  • 专业— 医疗领域的专业。有效值为PRIMARYCARECARDIOLOGYNEUROLOGYONCOLOGYRADIOLOGY, 和UROLOGY.

  • 类型— 音频的类型。必须为 DICTATIONCONVERSATION

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

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

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

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

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

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

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

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

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

Task 1:创建规范请求

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

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

    # HTTP verb method = "GET" # Service name service = "transcribe" # Amazon Region region = "Amazon Region" # Amazon Transcribe streaming-med 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 = "/medical-stream-transcription-websocket"
  3. 创建规范标头和签名标头。请注意规范标头尾部的 "\n"

    • 追加小写标头名称,后跟冒号。

    • 追加该标头的值的逗号分隔列表。请勿对有多个值的标头进行值排序。

    • 附加一个新行 (\n)。

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

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

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

    • 按字符代码点以升序顺序对参数名称进行排序。具有重复名称的参数应按值进行排序。例如,以大写字母 F 开头的参数名称排在以小写字母 b 开头的参数名称之前。

    • 请勿对以下任何非预留字符进行 URI 编码。RFC 3986定义:A-Z、a-z、0-9、连字符 (-)、下划线 (_)、句点 (.) 和波形符 (~)。

    • 使用 %XY 对所有其他字符进行百分比编码,其中“X”和“Y”为十六进制字符(0-9 和大写字母 A-F)。例如,空格字符必须编码为 %20(不像某些编码方案那样使用 “+”),扩展 UTF-8 字符必须采用 %xy%ZA%BC 格式。

    • 对参数值中的任何等于 (=) 字符进行双重编码。

    canonical_querystring = "X-Amz-Algorithm=" + algorithm canonical_querystring += "&X-Amz-Credential="+ URI-encode(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" canonical_querystring += "&specialty=PRIMARYCARE" canonical_querystring += "&type=DICTATION"
  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

Task 2:创建待签字符串

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

  • 创建字符串。

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

Task 3:计算签名

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

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

函数 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

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

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

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

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

    request_url = endpoint + canonical_uri + "?" + canonical_querystring

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

包括 WebSocket 请求标头

对 Amazon Transcribe Medical 的请求必须包含以下标头。通常,这些 Med 标头由您的 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.

  • 升级— 始终为websocket.

  • Origin— WebSocket 客户端的 URI。

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

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

处理 WebSocket 升级响应

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

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

HTTP/1.1 101 WebSocket 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 &type=dictation or conversation &specialty=medical specialty (must be Primary Care) &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 连接后,客户端就可以开始发送一系列音频帧。每个帧包含一个以事件流编码方式进行编码的数据帧。有关更多信息,请参阅 事件流编码

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

标头名称字节长度 标头名称(字符串) 标头值类型 值字符串字节长度 值字符串 (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 Medical 会使用包含事件流编码响应的终端 WebSocket 帧进行响应。该响应具有下表中描述的标头,以及包含描述性错误消息的响应正文。发送异常响应后,Amazon Transcribe Medical 会发送一个关闭帧。

标头名称字节长度 标头名称(字符串) 标头值类型 值字符串字节长度 值字符串 (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 Medical 在与客户端握手期间遇到问题。请再次尝试您的请求。

  • LimitExceededException— 客户端超出了并发流限制。有关更多信息,请参阅 。Amazon TranscribeService Quotas中的Amazon Web Services 常规参考. 减少要转录的流的数量。

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

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