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

# SpeakAndGetDigits
<a name="speak-and-get-digits"></a>

通过提供文本播放语音，并从客户那里收集双音多频 (DTMF) 数字。文本可以是纯文本或者语音合成标记语言 (SSML) 增强型文本，以通过添加暂停、强调某些单词或更改说话风格以及其他支持的 SSML 功能更好地控制 Amazon Chime SDK 生成语音的方式。如果发生失败，例如用户未输入正确的 DTMF 数字，该操作将播放“失败”语音，然后重播主语音，直到 SIP 媒体应用程序耗尽 `Repeat` 参数中定义的尝试次数。

Amazon Chime SDK 使用 Amazon Polly — 一项将文本转换为逼真语音的云服务，可提供标准和神经引擎，以提高语音质量并支持超过 20 种语言和 60 种语音。Amazon Polly 免费提供语音功能，但使用 Amazon Polly 需要付费。有关定价信息，请参阅 Amazon Polly [定价页面](https://aws.amazon.com/polly/pricing/)或账单控制面板。

**重要**  
使用 Amazon Polly 须遵守[AWS 服务条款](https://aws.amazon.com/service-terms/)，包括特定于 Machine Learn AWS ing 和人工智能服务的条款。

**Topics**
+ [使用 SpeakAndGetDigits 操作](#speak-digits-action)
+ [处理 ACTION\_SUCCESSFUL 事件](#speak-digits-success)
+ [处理 ACTION\_FAILED 事件](#speak-digits-fail)
+ [使用 Amazon Chime SDK 语音连接器服务相关角色](#speak-digits-policy)

## 使用 SpeakAndGetDigits 操作
<a name="speak-digits-action"></a>

以下示例显示典型的 `SpeakAndGetDigits` 操作：

```
{
    "SchemaVersion": "1.0",
    "Actions":[
        {
            "Type": "SpeakAndGetDigits",
            "Parameters": {
                "CallId": "{{call-id-1}}",          // required
                "InputDigitsRegex": "{{^\d{2}#$}}", // optional
                "SpeechParameters": {
                    "Text": "{{Hello World}}",      // required
                    "Engine": "{{neural}}",         // optional. Defaults to standard
                    "LanguageCode": "{{en-US}}",    // optional
                    "TextType": "{{text}}",         // optional
                    "VoiceId": "{{Joanna}}"         // optional. Defaults to Joanna
                },
                "FailureSpeechParameters": {
                    "Text": "{{Hello World}}",      // required
                    "Engine": "{{neural}}",         // optional. Defaults to the Engine value in SpeechParameters
                    "LanguageCode": "{{en-US}}",    // optional. Defaults to the LanguageCode value in SpeechParameters
                    "TextType": "{{text}}",         // optional. Defaults to the TextType value in SpeechParameters
                    "VoiceId": "{{Joanna}}"         // optional. Defaults to the VoiceId value in SpeechParameters
                },
                "MinNumberOfDigits": {{3}},         // optional
                "MaxNumberOfDigits": {{5}},         // optional
                "TerminatorDigits": ["{{#}}"],      // optional
                "InBetweenDigitsDurationInMilliseconds": {{5000}},  // optional
                "Repeat": {{3}},                    // optional
                "RepeatDurationInMilliseconds": {{10000}}           // required
            }
        }
    ]
}
```

**CallId**  
*描述* — Lambda 函数调用的参与者。`CallId` CallDetails   
*允许的值* — 有效的 `callID`  
*必填* — 是  
*默认值* — 否

**InputDigitsRegex**  
*描述* — 一种正则表达式模式，帮助确保用户输入正确的数字和字母。  
*允许的值* — 有效的正则表达式模式  
*必填* — 否  
*默认值* – 无

**SpeechParameters.Engine**  
*描述* — 指定在处理语音合成文本时使用的引擎：标准引擎或神经引擎。  
*允许的值* — `standard` \| `neural`  
*必填* — 否  
*默认值* — 标准

**SpeechParameters.LanguageCode**  
*描述* — 指定语言代码。仅在使用双语语音时需要。如果使用双语语音但未指定语言代码，则使用双语语音的默认语言。  
*允许的值* — [Amazon Polly 语言代码](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-LanguageCode)  
*必填* — 否  
*默认值* – 无

**SpeechParameters.Text**  
*描述* — 指定输入文本。如果指定 `ssml` 为 `SpeechParameters.TextType`，必须按照 SSML 格式输入文本。有关 SSML 的更多信息，请参阅 *Amazon Polly 开发人员指南*中的[由 SSML 文档生成语音](https://docs.aws.amazon.com/polly/latest/dg/ssml.html)。  
*允许的值* — 字符串  
*必填* — 是  
*默认值* – 无

**SpeechParameters.TextType**  
*描述* — 指定 `SpeechParameters.Text` 的文本格式。如未指定，默认使用 `text`。有关 SSML 的更多信息，请参阅 *Amazon Polly 开发人员指南*中的[由 SSML 文档生成语音](https://docs.aws.amazon.com/polly/latest/dg/ssml.html)。  
*允许的值* — `ssml` \| `text`  
*必填* — 否  
*默认值* — `text`

**SpeechParameters.VoiceId**  
*描述* — 用于朗读 `SpeechParameters.Text` 中文本的 Amazon Polly 语音的 ID。  
*允许的值* — [Amazon Polly 语音 ID](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-VoiceId)  
*必填* — 否  
*默认值* — Joanna

**FailureSpeechParameters.Engine**  
*描述* — 指定在处理客户在为语音合成输入无效响应而使用故障消息时使用的引擎：标准引擎或神经引擎。  
*允许的值* — `standard` \| `neural`  
*必填* — 否  
*默认值* — `SpeechParameters.Engine` 值

**FailureSpeechParameters.LanguageCode**  
*描述* — 指定客户输入无效响应时使用的语言代码。仅在使用双语语音时需要。如果您使用双语语音但未指定语言代码，则使用双语语音的默认语言。  
*允许的值* — [Amazon Polly 语言代码](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-LanguageCode)  
*必填* — 否  
*默认值* — `SpeechParameters.LanguageCode` 值。

**FailureSpeechParameters.Text**  
*描述* — 指定客户输入无效响应时所说的输入文本。如果指定 `ssml` 为 `FailureSpeechParameters.TextType`，必须按照 SSML 格式输入文本。  
*允许的值* — 字符串  
*必填* — 是  
*默认值* – 无

**FailureSpeechParameters.TextType**  
*描述* — 指定 `FailureSpeechParameters.Text` 中指定的输入文本是纯文本还是 SSML。默认值为纯文本。有关更多信息，请参阅 *Amazon Polly 开发人员指南*中的[由 SSML 文档生成语音](https://docs.aws.amazon.com/polly/latest/dg/ssml.html)。  
*允许的值* — `ssml` \| `text`  
*必填* — 否  
*默认值* — `SpeechParameters.Text` 值

**FailureSpeechParameters.VoiceId**  
*描述* — 用于朗读 `FailureSpeechParameters.Text` 中字符串的语音的 ID。  
*允许的值* — [Amazon Polly 语音 ID](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-VoiceId)  
*必填* — 是  
*默认值* — `SpeechParameters.VoiceId` 值

**MinNumberOfDigits**  
*描述* — 在超时或播放“调用失败”消息之前捕获的最小数字。  
*允许的值* — 大于或等于零  
*必填* — 否  
*默认值* — 0

**MaxNumberOfDigits**  
*描述* — 在没有终止数字的情况下停止前要捕获的最大数字位数。  
*允许的值* — 大于 `MinNumberOfDigits`  
*必填* — 否  
*默认值* — 128

**TerminatorDigits**  
*描述*-如果用户输入的数字少于 MaxNumberOfDigits  
*允许的值* — 以下任何一值：0、1、2、3、4、5、6、7、8、9、\# 或 \*  
*必填* — 否  
*默认值* — \#

**InBetweenDigitsDurationInMilliseconds**  
*描述* — 播放失败语音之前数字输入之间的等待时间（以毫秒为单位）。  
*允许的值* — 大于零  
*必填* — 否  
*默认值* — 如未指定，默认为 `RepeatDurationInMilliseconds` 值

**Repeat**  
*描述* — 尝试获取数字的总次数。如果忽略此参数，则默认值为尝试收集数字一次。  
*允许的值* — 大于零  
*必填* — 否  
*默认值* — 1

**RepeatDurationInMilliseconds**  
*描述* — 每次尝试获取数字的超时时间（以毫秒为单位）。  
*允许的值* — 大于零  
*必填* — 是  
*默认值* – 无

## 处理 ACTION\_SUCCESSFUL 事件
<a name="speak-digits-success"></a>

以下示例显示典型的 `ACTION_SUCCESSFUL` 事件。

```
{
    "SchemaVersion": "1.0",
    "Sequence": 3,
    "InvocationEventType": "ACTION_SUCCESSFUL",
    "ActionData": {
            "Type":  "SpeakAndGetDigits",
            "Parameters": {
                "CallId": "{{call-id-1}}",          
                "InputDigitsRegex":  "{{^\d{2}#$}}", 
                "SpeechParameters": {
                    "Engine":  "{{neural}}",         
                    "LanguageCode": "{{en-US}}",    
                    "Text":  "{{Hello World}}",           
                    "TextType":  "{{text}}",         
                    "VoiceId": "{{Joanna}}"         
                },
                "FailureSpeechParameters": {
                    "Engine":  "{{neural}}",         
                    "LanguageCode":  "{{en-US}}",    
                    "Text":  "{{Hello World}}",           
                    "TextType": "{{text}}",         
                    "VoiceId": "{{Joanna}}"         
                },
                "MinNumberOfDigits": {{3}},         
                "MaxNumberOfDigits": {{5}},         
                "TerminatorDigits": ["{{#}}"],      
                "InBetweenDigitsDurationInMilliseconds": {{5000}},  
                "Repeat": {{3}},                    
                "RepeatDurationInMilliseconds": {{10000}}           
            },
            "ReceivedDigits": "{{1234}}"
    },
    "CallDetails":{       
       ...
    }
}
```

## 处理 ACTION\_FAILED 事件
<a name="speak-digits-fail"></a>

以下示例显示典型的 `ACTION_FAILED` 事件。

```
{
    "SchemaVersion": "1.0",
    "Sequence":2,
    "InvocationEventType": "ACTION_FAILED",
    "ActionData":{
            "Type":  "SpeakAndGetDigits",
            "Parameters": {
                "CallId": "{{call-id-1}}",          
                "InputDigitsRegex":  "{{^\d{2}#$}}", 
                "SpeechParameters": {
                    "Engine":  "{{neural}}",         
                    "LanguageCode": "{{en-US}}",    
                    "Text":  "{{Hello World}}",           
                    "TextType":  "{{text}}",         
                    "VoiceId": "{{Joanna}}"         
                },
                "FailureSpeechParameters": {
                    "Engine":  "{{neural}}",         
                    "LanguageCode":  "{{en-US}}",    
                    "Text":  "{{Hello World}}",          
                    "TextType": "{{text}}",        
                    "VoiceId": "{{Joanna}}"        
                },
                "MinNumberOfDigits": {{3}},      
                "MaxNumberOfDigits": {{5}},        
                "TerminatorDigits": ["{{#}}"],      
                "InBetweenDigitsDurationInMilliseconds": {{5000}},  
                "Repeat": {{3}},                    
                "RepeatDurationInMilliseconds": {{10000}}         
            },
            "ErrorType":  "SystemException",
            "ErrorMessage":  "System error while running action"
    },
    "CallDetails":{       
       ...
    }
}
```

**错误处理**  
此表列出并描述了 `Speak` 操作引发的错误消息。


| 错误 | Message | Reason | 
| --- | --- | --- | 
| `AccessDenied` | `AWSServiceRoleForAmazonChimeVoiceConnector` 角色配置不正确。 | 用于向 Amazon Polly 发出请求的角色不存在或缺少权限。要解决这一问题，请参阅 [使用 Amazon Chime SDK 语音连接器服务相关角色](#speak-digits-policy) 部分中的相关步骤 | 
| `InvalidActionParameter` |   | 验证操作参数时出错。要查看此操作的可用参数及其选项，请参阅 Amazon Polly 开发人员指南中的 [SynthesizeSpeech](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html)。 | 
| `MissingRequiredActionParameter` | `Text` 是必填参数。 | 操作参数必须有 `Text` 值 | 
| `MissingRequiredActionParameter` | `Text` 限制为 1,000 个字符 | 文本超出了字符限制。 | 
| `SystemException` | 运行操作时出现系统错误。 | 运行操作时出现一个系统错误。 | 

## 使用 Amazon Chime SDK 语音连接器服务相关角色
<a name="speak-digits-policy"></a>

无需手动为 `Speak` 或 `SpeakAndGetDigits` 操作创建该服务相关角色。当你在 Amazon Chime 软件开发工具包控制台、或 AWS API 中创建或更新 SIP 媒体应用程序时 AWS Command Line Interface，Amazon Chime SDK 会为您创建服务相关角色。

有关更多信息，请参阅 *Amazon Chime SDK 管理员指南中*的[使用 Amazon Chime 服务相关角色](https://docs.aws.amazon.com/chime/latest/ag/using-service-linked-roles-stream.html)。