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

# RecordAudio
<a name="record-audio"></a>

允許 SIP 媒體應用程式記錄來自指定呼叫 ID 的媒體。例如，語音郵件應用程式和會議參與者公告。應用程式會記錄，直到達到您設定的持續時間，或使用者按下其中一個 `RecordingTerminators`，或應用程式偵測到靜音為止。在這些情況下， 動作會指示應用程式將產生的媒體檔案放入指定的 S3 儲存貯體。S3 儲存貯體必須屬於與 SIP 媒體應用程式相同的 AWS 帳戶。此外， 動作必須授予 Amazon Chime SDK Voice Connector 服務主體 [Amazon Chime SDK Voice Connector 服務主體](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) 的 `s3:PutObject`和 `s3:PutObjectAcl`許可`voiceconnector.chime.amazonaws.com`。

**注意**  
使用此功能進行的錄製可能受到有關記錄電子通訊的法律和法規的約束。您和您的最終使用者有責任遵守有關記錄的所有適用法律，包括正確通知記錄工作階段或通訊中的所有參與者正在記錄工作階段或通訊，並取得他們的同意。

下列範例將 `s3:PutObject`和 `s3:PutObjectAcl`許可授予 Amazon Chime SDK Voice Connector 服務主體。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "SMARead",
            "Effect": "Allow",
            "Principal": {
                "Service": "voiceconnector.chime.amazonaws.com"
            },
            "Action": [                
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::{{bucket-name}}/*"
        }
    ]
}
```

------

以下範例會在呼叫者按下井字號 (\#) 或經過 10 秒沒有活動時停止記錄，或呼叫者保持靜音 3 秒，並將產生的媒體檔案寫入 `RecordingDestination` 參數定義的位置。

**注意**  
此範例使用 `CallId` 參數。您可以改為使用 `ParticipantTag` 參數，但不能同時使用兩者。

```
{
    "Type": "RecordAudio",
    "Parameters": {
        "CallId": "{{call-id-1}}",
        "DurationInSeconds": "{{10}}",
        "SilenceDurationInSeconds": {{3}},
        "SilenceThreshold": {{100}},
        "RecordingTerminators": [
            "{{#}}"
        ],
        "RecordingDestination": {
            "Type": "S3",
            "BucketName": "{{valid-bucket-name}}",
            "Prefix": "{{valid-prefix-name}}"
        }
    }
}
```

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

**ParticipantTag**  
*描述* – `ParticipantTag` 中其中一個已連線參與者的描述 `CallDetails`  
*允許的值* – `LEG-A`或 `LEG-B`  
*必要* – 否  
*預設值* – 如果您指定 `ParticipantTag` ，則叫用`callLeg`忽略的預設值 `CallId`

**RecordingDestination.Type**  
*描述* – 目的地的類型。只有 S3。  
*允許的值* – S3  
*必要* – 是  
*預設值* — 無

**RecordingDestination.BucketName**  
*描述* – 有效的 S3 儲存貯體名稱。儲存貯體必須能夠存取 [Amazon Chime SDK Voice Connector 服務主體](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) `voiceconnector.chime.amazonaws.com`。  
*允許的值* – Amazon Chime SDK 可存取 `s3:PutObject`和 `s3:PutObjectAcl`動作的有效 S3 儲存貯體。  
*必要* – 是  
*預設值* — 無

****RecordingDestination.Prefix****  
*描述* – 錄製檔案的 S3 字首  
*允許的值* – 包含最多 979 個安全字元的有效字首名稱。如需安全字元的詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的[安全字元](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-guidelines-safe-characters)。  
*必要* – 否  
*預設* – 無。如果未指定，則記錄會儲存到 S3 儲存貯體的根目錄。

**DurationInSeconds**  
*描述* – 記錄的持續時間，以秒為單位  
*允許的值* – >0  
*必要* – 否  
*預設值* — 無

****SilenceDurationInSeconds****  
*描述* – 無聲的持續時間，以秒為單位，之後錄音會停止。如果未指定，則會停用靜音偵測。  
*允許的值* – 【1；1000】  
*必要* – 否  
*預設值* – 200

****SilenceThreshold****  
*描述* – 被視為「靜音」的雜訊等級。如果您未指定 `SilenceDurationInSeconds`，則會忽略此參數。  

**參考值 （將雜訊視為靜音的雜訊層級和閾值）：**
+ 1-30dB 或以下，例如安靜的房間
+ 100-40-50 dB，例如低語或安靜的辦公室
+ 200-60dB，例如擁擠的辦公室
+ 1000 – 75 dB，例如大聲人物或音樂
*允許的值* – 【1；1000】  
*必要* – 否  
*預設值* – 200

**RecordingTerminators**  
*描述* – 列出所有可用的錄製終止程式。  
*允許的值* – 來自 [123456789\*0\# 的單一數字和符號陣列】  
*必要* – 是  
*預設值* — 無

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

當錄製結束時，Amazon Chime SDK SIP 媒體應用程式會呼叫 AWS Lambda 函數，並將 ACTION\_SUCCESSFUL 事件連同調用結果傳遞給該函數。

```
{
    "SchemaVersion": "1.0",
    "Sequence": INTEGER,
    "InvocationEventType": "ACTION_SUCCESSFUL",
    "ActionData": {
        "Type" : "RecordAudio",
        "Parameters": {
           ...           
        },
        "RecordingDestination": {
            "Type": "S3",
            "BucketName": "{{valid-bucket-name}}",
            "Key": "{{valid-S3-key}}"              
        },
        "RecordingTerminatorUsed":"{{#}}"
    },
    "CallDetails": {
        ...
    }
}
```

`ACTION_SUCCESSFUL` 事件包含 `ActionData`，其中包含下列欄位：

**Type**  
*描述* – 動作的類型 `RecordAudio`。

**Parameters**  
*描述* – 動作的參數。

**RecordingDestination.Type**  
*描述* – 目的地的類型。只有 S3。

**RecordingDestination.BucketName**  
*描述* – 包含錄製檔案的 S3 儲存貯體。

**RecordingDestination.Key**  
*描述* – 錄製檔案的 S3 金鑰。

**RecordingTerminatorUsed**  
*描述* - 用來停止記錄的終止程式 - 其中一個在 `RecordingTerminators` 參數中傳遞的終止程式。如果錄製在達到最長持續時間 (`DurationInSeconds`) 或因為靜音 (`SilenceDurationInSeconds`) 而停止，則此鍵/值對不會包含在輸出中。

**錯誤處理**  
對於驗證錯誤，SIP 媒體應用程式會使用適當的錯誤訊息呼叫 AWS Lambda 函數。下表列出可能的錯誤訊息。


|  錯誤  |  訊息  |  Reason  | 
| --- | --- | --- | 
| `InvalidActionParameter` | `CallId` 動作的 或 `ParticipantTag` 參數無效。<br />`DurationInSeconds` 參數值無效。<br />`SilenceDurationInSeconds` 參數值無效。<br />`SilenceThreshold` 參數值無效。<br />`RecordingDestination` 參數值無效。<br />將錄製上傳至 S3 儲存貯體時發生錯誤。 | 任何參數都是無效的。 | 
| `SystemException` | 執行 動作時發生系統錯誤。 | 執行 動作時發生另一種類型的系統錯誤。 | 

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

當動作無法在通話腿上記錄媒體時，SIP 媒體應用程式會使用`ACTION_FAILED`事件類型叫用 AWS Lambda 函數。請參閱以下範例。

```
{
    "SchemaVersion": "1.0",
    "Sequence": {{5}},
    "InvocationEventType": "ACTION_FAILED",
    "ActionData": {
        "Type" : "RecordAudio",
        "Parameters": {
           ...           
        },
        "ErrorType": "InvalidActionParameter",
        "ErrorMessage": "RecordingDestination parameter value is invalid."
    },
    "CallDetails": {
        ...
    }
}
```

請參閱 GitHub 上的工作範例：https：//[https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)