本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

透過提供文字並從使用者收集雙音多頻率 (DTMF) 數字來播放語音。文字可以是純文字或語音合成標記語言 (SSML) 增強文字，透過新增暫停、強調特定單字或變更說話風格等支援 SSML 功能，提供更多對 Amazon Chime SDK 如何產生語音的控制。如果發生失敗，例如使用者未輸入正確的 DTMF 數字數，動作會播放「失敗」語音，然後重播主要語音，直到 SIP 媒體應用程式耗盡 `Repeat` 參數中定義的嘗試次數。

Amazon Chime SDK 使用 Amazon Polly，這是一種將文字轉換為逼真的語音的雲端服務，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/)，包括 AWS Machine Learning and Artificial Intelligence Services 特有的條款。

**Topics**
+ [使用 SpeakAndGetDigits動作](#speak-digits-action)
+ [處理ACTION\$1SUCCESSFUL事件](#speak-digits-success)
+ [處理ACTION\$1FAILED事件](#speak-digits-fail)
+ [使用 Amazon Chime SDK Voice Connector 服務連結角色](#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` \$1 `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` \$1 `text`  
*必要* – 否  
*預設值* – `text`

**SpeechParameters.VoiceId**  
*描述* – 用於在 中說出文字的 Amazon Polly 語音 ID`SpeechParameters.Text`。  
*允許的值* – [Amazon Polly IDs](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-VoiceId)  
*必要* – 否  
*預設值* – Joanna

**FailureSpeechParameters.Engine**  
*描述* – 指定在處理客戶輸入無效語音合成回應時使用的引擎 – 標準或神經。  
*允許的值* – `standard` \$1 `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` \$1 `text`  
*必要* – 否  
*預設值* – `SpeechParameters.Text`值

**FailureSpeechParameters.VoiceId**  
*描述* – 用於在 中說出字串的語音 ID`FailureSpeechParameters.Text`。  
*允許的值* – [Amazon Polly IDs](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 \$1 或 \$1  
*必要* – 否  
*預設值* – \$1

**InBetweenDigitsDurationInMilliseconds**  
*描述* – 播放失敗語音之前，數字輸入之間的等待時間，以毫秒為單位。  
*允許的值* – 大於零  
*必要* – 否  
*預設值* – 如果未指定，則預設為 `RepeatDurationInMilliseconds`值

**Repeat**  
*描述* – 嘗試取得數字的總數。如果您省略此參數，則預設為嘗試收集數字一次。  
*允許的值* – 大於零  
*必要* – 否  
*預設值* – 1

**RepeatDurationInMilliseconds**  
*描述* – 每次嘗試取得數字時，以毫秒為單位的逾時。  
*允許的值* – 大於零  
*必要* – 是  
*預設值* — 無

## 處理ACTION\$1SUCCESSFUL事件
<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\$1FAILED事件
<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`動作擲回的錯誤訊息。


| 錯誤 | 訊息 | 原因 | 
| --- | --- | --- | 
| `AccessDenied` | `AWSServiceRoleForAmazonChimeVoiceConnector` 角色未正確設定。 | 用於向 Amazon Polly 提出請求的角色不存在或缺少許可。若要解決此問題，請參閱 [使用 Amazon Chime SDK Voice Connector 服務連結角色](#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 Voice Connector 服務連結角色
<a name="speak-digits-policy"></a>

您不需要手動為 `Speak`或 `SpeakAndGetDigits`動作建立服務連結角色。當您在 Amazon Chime SDK 主控台、 AWS Command Line Interface或 AWS API 中建立或更新 SIP 媒體應用程式時，Amazon Chime SDK 會為您建立服務連結角色。

如需詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的使用 Amazon Chime 服務連結角色](https://docs.aws.amazon.com/chime/latest/ag/using-service-linked-roles-stream.html)。 **