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

# Speak
<a name="speak"></a>

您可以提供文字，在任何通話腿上播放語音。您可以使用純文字或語音合成標記語言 (SSML)。SSML 透過新增停頓、強調某些單字或變更說話風格，進一步控制 Amazon Chime SDK 如何產生語音。

Amazon Chime SDK 使用 Amazon Polly 服務來轉換text-to-speech。Amazon Polly 可讓您選擇標準或神經引擎，以提升語音品質。Amazon Polly 支援超過 20 種語言和 60 種語音，以自訂應用程式的使用者體驗。Amazon Chime SDK 免費提供語音功能，但您需付費使用 Amazon Polly。如需定價資訊，請參閱 Amazon Polly [定價頁面](https://aws.amazon.com/polly/pricing/)或帳單儀表板。

**重要**  
使用 Amazon Polly 受 [ AWS 服務條款 ](https://aws.amazon.com/service-terms/)的約束，包括 AWS Machine Learning 和人工智慧服務的特定條款。

**Topics**
+ [使用 Speak動作](#speak-action)
+ [處理ACTION\_SUCCESSFUL事件](#speak-action-success)
+ [處理ACTION\_FAILED事件](#speak-action-fail)
+ [程式流程](#speak-flow)

## 使用 Speak動作
<a name="speak-action"></a>

下列範例顯示 `Speak`動作的典型使用方式。

```
{
    "SchemaVersion": "1.0",
    "Actions":[
        {
            "Type": "Speak",
            "Parameters": {
                "Text": "{{Hello, World!}}",        // required
                "CallId": "{{call-id-1}}",          // required
                "Engine": "{{neural}}",             // optional. Defaults to standard
                "LanguageCode": "{{en-US}}",        // optional
                "TextType": "{{text}}",             // optional
                "VoiceId": "{{Joanna}}"             // optional. Defaults to Joanna
            }
        }
    ]
}
```

**CallId**  
*描述* – Lambda 函數調用`CallId`之 中的參與者`CallDetails`的  
*允許的值* – 有效的呼叫 ID  
*必要* – 是  
*預設值* — 無

**Text**  
*描述* – 指定要合成為語音的輸入文字。如果您將 指定`ssml`為 `TextType`，請遵循輸入文字的 SSML 格式。  
*允許的值* – 字串  
*必要* – 是  
*預設值* — 無

**Engine**  
*描述* – 指定處理語音合成文字時要使用的引擎 - 標準或神經。  
*允許的值* – 標準 \| 神經  
*必要* – 否  
*預設值* – 標準

**LanguageCode**  
*描述* – 指定語言代碼。只有在使用雙語語音時才需要。如果您使用不含語言代碼的雙語語音，則會使用雙語語音的預設語言。  
*允許的值* – [ Amazon Polly 語言代碼](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-LanguageCode)  
*必要* – 否  
*預設值* — 無

**TextType**  
*描述* – 指定輸入文字、純文字或 SSML 的類型。如果未指定輸入類型，則會使用純文字做為預設值。如需 SSML 的詳細資訊，請參閱《*Amazon Polly 開發人員指南*》中的[從 SSML 文件產生語音](https://docs.aws.amazon.com/polly/latest/dg/ssml.html)。  
*允許的值* – ssml \| 文字  
*必要* – 否  
*預設值* — 無

**VoiceId**  
*描述* – 指定您要使用的語音 ID。  
*允許的值* – [Amazon Polly IDs](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html#polly-SynthesizeSpeech-request-VoiceId)  
*必要* – 否  
*預設值* – Joanna

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

下列範例顯示動作的典型`ACTION_SUCCESSFUL`事件，該動作使用 Amazon Polly `Joanna`的語音，將文字 "Hello World" 合成為英文語音。

```
{
    "SchemaVersion": "1.0",
    "Sequence": {{3}},
    "InvocationEventType": "ACTION_SUCCESSFUL",
    "ActionData": {
       "Type": "Speak",
       "Parameters": {
          "CallId": "{{call-id-1}}",          
          "Engine":  "{{neural}}",             
          "LanguageCode":  "{{en-US}}",        
          "Text": "{{Hello World}}",          
          "TextType":  "{{text}}",             
          "VoiceId":  "{{Joanna}}"        
       }
    },
    "CallDetails":{       
       ...
    }
}
```

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

下列範例顯示與先前範例中使用之相同`ACTION_FAILED`事件的典型事件。

```
{
    "SchemaVersion": "1.0",
    "Sequence":{{2}},
    "InvocationEventType": "ACTION_FAILED",
    "ActionData":{
       "Type": "Speak",
       "Parameters": {
          "CallId": "{{call-id-1}}",          
          "Engine":  "{{neural}}",             
          "LanguageCode":  "{{en-US}}",        
          "Text": "{{Hello  World}}",          
          "TextType":  "{{text}}",             
          "VoiceId":  "{{Joanna}}"        
       },
       "ErrorType": "SystemException",
       "ErrorMessage": "System error while running  action"
    },
    "CallDetails":{       
       ...
    }
}
```

**錯誤處理**  
此資料表列出並描述 `Speak`動作擲回的錯誤訊息。


| 錯誤 | 訊息 | Reason | 
| --- | --- | --- | 
| `AccessDenied` | `AWSServiceRoleForAmazonChimeVoiceConnector` 服務連結角色未正確設定。 | 用於向 Amazon Polly 提出請求的服務連結角色不存在或缺少許可。若要解決此問題，請參閱 [使用 Amazon Chime SDK Voice Connector 服務連結角色](speak-and-get-digits.md#speak-digits-policy)一節中的步驟 | 
| `InvalidActionParameter` |   | 驗證動作參數時發生錯誤。如需參數的詳細資訊，請參閱《*Amazon Polly 開發人員指南*》中的 [SynthesizeSpeech API](https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech)。 | 
| ActionExecutionThrottled | Amazon Polly 正在調節合成語音的請求。 | 對 Amazon Polly 的請求會傳回限流例外狀況。如需 Amazon Polly 限流限制的詳細資訊，請參閱 [ https：//https://docs.aws.amazon.com/polly/latest/dg/limits.html\#limits-throttle。 ](https://docs.aws.amazon.com/polly/latest/dg/limits.html#limits-throttle) | 
| `MissingRequiredActionParameter` | `Text` 是必要的參數。 | 有動作參數必須具有 `Text`值 | 
| `MissingRequiredActionParameter` | `Text` 限制為 1，000 個字元 | 文字超過字元限制。 | 
| `SystemException` | 執行動作時發生系統錯誤。 | 執行 動作時發生系統錯誤。 | 

## 程式流程
<a name="speak-flow"></a>

下圖顯示為發起人啟用 `Speak`動作的程式流程。在此範例中，發起人會聽到 

![圖表顯示為發起人啟用 Speak動作的程式流程。](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/Speak1.png)


**在圖表中**  
使用軟體電話，來電者會輸入已註冊至 SIP 媒體應用程式的號碼。應用程式使用 SIP `INVITE`方法，並向發起人傳送`Trying (100)`回應。這表示下一個躍點伺服器收到呼叫請求。然後， SIP 應用程式會使用 `INVITE`來聯絡端點。建立連線後，應用程式會傳送`Ringing (180)`回應給發起人，並開始提醒。

然後，SIP 媒體應用程式會將`NEW_INBOUND_CALL`事件傳送至 Lambda 函數，該函數會回應包含呼叫者 ID 和您要轉換為語音的文字`Speak`的動作。然後，SIP 應用程式會傳送`200 (OK)`回應，指出通話已接聽。通訊協定也會啟用媒體。

如果`Speak`動作成功並將文字轉換為語音，則會將`ACTION_SUCCESSFUL`事件傳回 SIP 媒體應用程式，並傳回下一組動作。如果動作失敗，SIP 媒體應用程式會將`ACTION_FAILED`事件傳送至 Lambda 函數，該函數會以一組`Hangup`動作回應。應用程式掛斷發起人，並將`HANGUP`事件傳回至 Lambda 函數，而 Lambda 函數不會採取進一步的動作。



下圖顯示 程式流程，而 會啟用受話方`Speak`的動作。

![顯示啟用受話方Speak動作之程式流程的圖表。您可以在任何橋接呼叫上執行此操作。](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/Speak2.png)


**在圖表中**  
發起人輸入已註冊至 SIP 媒體應用程式的號碼，而應用程式會如上圖所述回應。當 Lambda 函數收到`NEW_INBOUND_CALL`事件時，它會將 [CallAndBridge](call-and-bridge.md)動作傳回 SIP 應用程式。應用程式接著會使用 SIP `INVITE`方法，將 `Trying (100)`和 `Ringing (180)`回應傳送給受話方。

如果受話方接聽，SIP 媒體應用程式會接收`200 (OK)`回應，並傳送相同的回應給發起人。這會建立媒體，而 SIP 應用程式會將 [CallAndBridge](call-and-bridge.md)動作`ACTION_SUCCESSFUL`的事件傳送至 Lambda 函數。然後，函數會將 Speak 動作和資料傳回至 SIP 應用程式，其會轉換