本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# StartCallRecording
`StartCallRecording` 操作开始呼叫分支的录音。您可以在 SIP 媒体应用程序中按需或作为 SIP 事件的响应开始通话录音。
+ 要开始按需录制通话，您可以使用 `UpdateSipMediaApplication` API 调用您的应用程序并返回 `StartCallRecording` 操作。
+ 要开始通话录音以响应 SIP 事件，可在应用程序中返回 `StartCallRecording` 操作。
您可以指定录制传入分支的音频轨道和/或传出分支的音频轨道。下面几个部分介绍如何使用 `StartCallRecording` 操作。
**注意**
使用此功能录制的录音可能会受有关电子通信录制的法律或法规的约束。您和您的最终用户有责任遵守与录音有关的所有适用法律，包括适当通知录制会话或通信中的所有参与者正在录制会话或通信，并获得他们的许可。
**Topics**
+ [请求采取 StartCallRecording 行动](#request-start)
+ [指定录制目标](#recording-destination)
+ [授予 Amazon S3 存储桶权限](#grant-s3-perms)
+ [操作成功响应](#action-successful)
+ [操作错误响应](#action-error)
## 请求采取 StartCallRecording 行动
以下示例显示如何为 `BOTH` 轨道请求 `StartCallRecording` 操作。
```
{
"SchemaVersion": "1.0",
"Actions": [
{
"Type": "StartCallRecording",
"Parameters":
{
"CallId": "{{call-id-1}}",
"Track": "{{BOTH}}",
"Destination":
{
"Type": "S3",
"Location": "{{valid-bucket-name-and-optional-prefix}}"
}
}
}
]
}
```
**CallId**
*描述* — `CallId` AWS Lambda 函数调用`CallDetails`中的参与者
*允许的值* — 有效的调用 ID
*必填* — 是
*默认值* – 无
**Track**
*描述*— 通话录音的音频 `Track`。
*允许的值* — `BOTH`、`INCOMING` 或 `OUTGOING`
*必填* — 是
*默认值* – 无
**Destination.Type**
*描述* — 目的地类型。只允许使用 Amazon S3。
*允许的值* — Amazon S3
*必填* — 是
*默认值* – 无
**Destination.Location**
*描述* — 有效的 Amazon S3 存储桶和可选 Amazon S3 键前缀。存储桶必须有权访问 Amazon Chime SDK 语音连接器服务主体，即 voiceconnector.chime.amazonaws.com。
*允许的值* — Amazon Chime SDK 有权访问 `s3:PutObject` 和 `s3:PutObjectAcl` 操作的有效 Amazon S3 路径。
*必填* — 是
*默认值* – 无
## 指定录制目标
Amazon Chime SDK 将通话录音发送至您的 Amazon S3 存储桶。存储桶必须属于您的 AWS 账户。您需要在 `StartCallRecording` 操作的 `Destination` 参数中指定存储桶的位置。`Destination` 参数中的 `Type` 字段必须是 `S3`。`Location` 字段由您的 Amazon S3 存储桶以及用于传送通话录音的可选对象键前缀组成。
SIP 媒体应用程序使用指定的 `Location`、呼叫分支的日期和时间、事务 ID 和呼叫 ID 格式化 Amazon S3 对象键。`StartCallRecording` 操作响应会返回完整的 Amazon S3 对象键。
当您仅在 `Location` 字段中提供 Amazon S3 存储桶时，SIP 媒体应用程序会在 Amazon S3 路径上附加一个默认前缀 `Amazon-Chime-SMA-Call-Recordings`。SIP 媒体应用程序还会附加通话开始时间的年、月和日，以帮助梳理录音。以下示例显示带有默认前缀的一般格式的 Amazon S3 路径。此示例使用 `myRecordingBucket` 作为 `Location` 值。
```
{{myRecordingBucket}}/Amazon-Chime-SMA-Call-Recordings/2019/03/01/2019–03–01–17–10–00–010_c4640e3b–1478–40fb-8e38–6f6213adf70b_7ab7748e–b47d–4620-ae2c–152617d3333c.wav
```
以下示例显示通话录音 Amazon S3 路径中表示的数据。
```
{{s3Bucket}}/Amazon-Chime-SMA-Call-Recordings/{{year}}/{{month}}/{{date}}/{{year-month-date-hour-minute-second-millisecond_transactionId_callId}}.wav
```
当您在 `Location` 字段中提供 Amazon S3 存储桶和对象键前缀时，SIP 媒体应用程序将在目标 Amazon S3 路径中使用您的对象键前缀，而非默认前缀。以下示例显示带有您的前缀的一般格式的通话录音 Amazon S3 路径。例如，您可以将 myRecordingBucket/technicalSupport /english 指定为。`Location`
```
{{myRecordingBucket}}/{{technicalSupport}}/english/2019/03/01/2019–03–01–17–10–00–010_c4640e3b1478–40fb–8e38-6f6213adf70b_7ab7748e–b47d–4620–ae2c–152617d3333c.wav
```
以下示例显示 Amazon S3 路径中的数据。
```
{{s3Bucket}}/{{yourObjectKeyPrefix}}/{{year}}/{{month}}/{{date}}/{{year-month-date-hour-minute-second-millisecond}}_{{transactionId}}_{{callId}}.wav
```
发送到您的 Amazon S3 存储桶的录音包含有关呼叫分支的其他 [Amazon S3 对象元数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。下表列出了受支持的 Amazon S3 对象元数据。
| Name | 说明 |
| --- | --- |
| transaction-id | 呼叫的事务 ID。 |
| call-id | CallId AWS Lambda 函数调 CallDetails 用的参与者 |
| recording-duration | 通话录音时长（秒） |
| recording-audio-file-format | 以互联网媒体类型表示的通话录音音频文件格式 |
## 授予 Amazon S3 存储桶权限
您的目标 Amazon S3 存储桶必须与您的应用程序属于同一个 AWS 账户。此外，您必须向 Amazon Chime SDK 语音连接器服务主体，即 `voiceconnector.chime.amazonaws.com`，授予 `s3:PutObject` 和 `s3:PutObjectAcl` 的访问权限。以下示例授予适当的权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SIP media applicationRead",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::{{bucket-name}}/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{123456789012}}"
}
}
}
]
}
```
------
PSTN 音频服务代表您的 SIP 媒体应用程序对 S3 存储桶进行读写操作。为避免[混淆代理问题](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)，您可以将 S3 存储桶的访问限制为单个 SIP 媒体应用程序。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SIP media applicationRead",
"Effect": "Allow",
"Principal": {
"Service": "voiceconnector.chime.amazonaws.com"
},
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::{{bucket-name}}/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{111122223333}}",
"aws:SourceArn": "arn:aws:chime:{{us-east-1}}:{{111122223333}}:sma/{{sip-media-application-id}}"
}
}
}
]
}
```
------
## 操作成功响应
在呼叫段成功启动呼叫录音后，SIP 媒体应用程序将调用`ACTION_SUCCESSFUL`事件 AWS Lambda 类型的函数。响应中会返回通话记录的位置。
```
{
"SchemaVersion": "1.0",
"Sequence": INTEGER,
"InvocationEventType": "ACTION_SUCCESSFUL",
"ActionData": {
"Type" : "StartCallRecording",
"Parameters": {
"CallId": "{{call-id-1}}",
"Track": "BOTH",
"Destination": {
"Type": "S3",
"Location": "{{valid-bucket-name}}"
}
}
"CallRecordingDestination": {
"Type": "S3",
"Location": "{{call-recording-bucket-and-key}}"
}
}
"CallDetails": {
...
}
}
```
## 操作错误响应
对于验证错误，SIP 媒体应用程序调用 AWS Lambda 函数时会显示相应的错误消息。下表列出错误消息。
| 错误 | Message | Reason |
| --- | --- | --- |
| `InvalidActionParameter` | 操作的 `CallId` 参数无效。 | 任何参数无效。 |
| `SystemException` | 运行操作时出现系统错误。 | 运行操作时出现另一种类型的系统错误。 |
当操作未能在呼叫分支上录制媒体时，SIP 媒体应用程序将调用 `ActionFailed` 事件类型的 AWS Lambda 函数。
以下示例显示典型错误响应。
```
{
"SchemaVersion": "1.0",
"Sequence": 5,
"InvocationEventType": "ACTION_FAILED",
"ActionData": {
"Type" : "StartCallRecording",
"Parameters": {
"CallId": "{{call-id-1}}",
"Track": "BOTH",
"Destination": {
"Type": "S3",
"Location": "{{valid-bucket-name}}"
}
}
"Error": "NoAccessToDestination: Error while accessing destination"
}
"CallDetails": {
...
}
}
```
参见 GitHub以下方面的工作示例：[https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)