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

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

允许 SIP 媒体应用程序录制给定调用 ID 的媒体。例如，语音邮件应用程序和会议参与者通知。应用程序会进行录制，直到达到您设置的持续时间，或用户按下其中一个 `RecordingTerminators`，或应用程序检测到沉默。在这些情况下，该操作会指示您的应用程序将生成的媒体文件放入指定的 S3 存储桶中。S3 存储桶必须与 SIP 媒体应用程序属于同一个 AWS 账户。此外，该操作必须给予 `s3:PutObject` 和 `s3:PutObjectAcl` 访问 Amazon Chime SDK 语音连接器服务主体 [Amazon Chime SDK 语音连接器服务主体](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html)（`voiceconnector.chime.amazonaws.com`）的权限。

**注意**  
使用此功能录制的录音可能会受有关电子通信录制的法律或法规的约束。您和您的最终用户有责任遵守与录音有关的所有适用法律，包括适当通知录制会话或通信中的所有参与者正在录制会话或通信，并获得他们的许可。

以下示例向 `s3:PutObject` 和 `s3:PutObjectAcl` 提供了访问 Amazon Chime SDK 语音连接器服务主体的权限。

------
#### [ 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/*"
        }
    ]
}
```

------

以下示例显示在调用者按下井号键 (\$1) 后，或者在 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**  
*描述* — `CallDetails` 中一个已连接参与者的 `ParticipantTag`  
*允许的值* — `LEG-A` 或 `LEG-B`  
*必填* — 否  
*默认值* — 已调用 `callLeg` 的 `ParticipantTag`，如指定 `CallId`，则忽略该值

**RecordingDestination.Type**  
*描述* — 目的地类型。仅 S3。  
*允许的值* — S3  
*必填* — 是  
*默认值* – 无

**RecordingDestination.BucketName**  
*描述* — 有效的 S3 存储桶名称。存储桶必须有权访问 [Amazon Chime SDK 语音连接器服务主体](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-50dB，例如耳语或安静的办公室
+ 200 — 60dB，例如拥挤的办公室
+ 1000 — 75dB，例如吵闹的人或音乐
*允许的值* — [1;1000]  
*必填* — 否  
*默认值* — 200

**RecordingTerminators**  
*描述* — 列出所有可用的录制终止符。  
*允许的值* — 来自 [123456789\$10\$1] 的个位数和符号的数组  
*必填* — 是  
*默认值* – 无

## 处理 ACTION\$1SUCCESSFUL 事件
<a name="handle-action-successful"></a>

录制结束后，Amazon Chime SDK SIP 媒体应用程序会调用该 AWS Lambda 函数，并将 ACTION\$1SUCCESSUCCESS 事件以及调用结果传递给该函数。

```
{
    "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 函数时会显示相应的错误消息。下表列出可能的错误消息。


|  错误  |  Message  |  Reason  | 
| --- | --- | --- | 
|  `InvalidActionParameter`  |  操作的 `CallId` 或 `ParticipantTag` 参数无效。 `DurationInSeconds` 参数值无效。 `SilenceDurationInSeconds` 参数值无效。 `SilenceThreshold` 参数值无效。 `RecordingDestination` 参数值无效。 将录音上传到 S3 存储桶时出错。  |  任何参数无效。  | 
|  `SystemException`  |  运行操作时出现系统错误。  |  运行操作时出现另一种类型的系统错误。  | 

## 处理 ACTION\$1FAILED 事件
<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://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)