本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 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`的音訊。
*允許的值* – `INCOMING`、 `BOTH`或 `OUTGOING`
*必要* – 是
*預設值* — 無
**Destination.Type**
*描述* – 目的地的類型。僅允許 Amazon S3。
*允許的值* – Amazon S3
*必要* – 是
*預設值* — 無
**Destination.Location**
*描述* – 有效的 Amazon S3 儲存貯體和選用的 Amazon S3 金鑰字首。儲存貯體必須具有 Amazon Chime SDK Voice Connector 服務主體的許可，https：//voiceconnector.chime.amazonaws.com。
*允許的值* – Amazon Chime SDK 對 和 動作具有權限的有效 Amazon S3 路徑。 `s3:PutObject` `s3:PutObjectAcl`
*必要* – 是
*預設值* — 無
## 指定錄製目的地
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-Chime-SMA-Call-Recordings`至 Amazon S3 路徑。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 物件中繼資料。
| 名稱 | 描述 |
| --- | --- |
| transaction-id | 電話的交易 ID |
| call-id | AWS Lambda 函數呼叫的 CallDetails 中參與者的 CallIdCallId |
| recording-duration | 通話記錄持續時間，以秒為單位 |
| recording-audio-file-format | 以網際網路媒體類型表示的通話錄音音訊檔案格式 |
## 授予 Amazon S3 儲存貯體許可
您的目的地 Amazon S3 儲存貯體必須屬於與您應用程式相同的 AWS 帳戶。此外， 動作必須向 Amazon Chime SDK Voice Connector 服務主體 授予 `s3:PutObject`和 `s3:PutObjectAcl`許可`voiceconnector.chime.amazonaws.com`。下列範例會授予適當的許可。
------
#### [ 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 Media Application 讀取和寫入您的 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 函數。下表列出錯誤訊息。
| 錯誤 | 訊息 | 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：//[https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)