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

# 将调用路由到 Amazon Chime SDK PSTN 音频的 AWS Lambda 函数 ()AWS CLI
<a name="route-calls-events-cli"></a>

本教程将指导您完成使用 Amazon Chime SDK PSTN 音频服务设置到 Lambda 函数的呼叫路由的过程。您将学习如何创建 Lambda 函数、设置 SIP 媒体应用程序以及配置 SIP 规则来处理来电。

## 先决条件
<a name="route-calls-events-cli-prerequisites"></a>

在开始本教程之前，请务必执行以下操作：
+ 安装 AWS CLI。有关更多信息，请参阅《AWS CLI 用户指南》**中的[安装或更新到最新版本的 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
+ 使用适当的 AWS CLI 凭据配置您的。如果尚未设置凭证，请运行 `aws configure`。
+ 对 Amazon Chime 软件开发 AWS Lambda 工具包的概念有基本的了解。
+ 设置足够的权限以在您的 AWS 账户中创建和管理 Amazon Chime 软件开发工具包和 Lambda 资源。
+ 对于基于电话号码的路由，您需要在 Amazon Chime SDK 的电话号码清单中有一个电话号码。
+ 对于基于语音连接器的路由，您需要在帐户中配置语音连接器。

## 成本注意事项
<a name="route-calls-events-cli-cost"></a>

本教程包含清理说明，以确保完成后不会产生持续的费用。有关更多信息，请参阅 [Amazon Chime 软件开发工具包](https://aws.amazon.com/chime/chime-sdk/pricing/)定价。

让我们开始为 Amazon Chime SDK PSTN 音频设置呼叫路由。

## 搜索和配置电话号码
<a name="route-calls-events-cli-search-provision"></a>

在使用电话号码触发器创建 SIP 规则之前，您需要在 Amazon Chime SDK 库存中包含电话号码。以下是搜索可用电话号码并进行配置的方法。

**Example : 搜索可用的电话号码**  

```
# Search for available toll-free phone numbers
aws chime-sdk-voice search-available-phone-numbers \
  --phone-number-type TollFree \
  --country US \
  --toll-free-prefix 844 \
  --max-results 5 \
  --region us-east-1
```

此命令在美国搜索前缀为 844 的可用免费电话号码。您可以修改参数以搜索不同类型的数字。

**Example : 配置电话号码**  
找到可用的电话号码后，您可以使用以下命令进行配置：  

```
# Order a phone number
aws chime-sdk-voice create-phone-number-order \
  --product-type SipMediaApplicationDialIn \
  --e164-phone-numbers "+18445550100" \
  --region us-east-1
```

`+18445550100`替换为搜索结果中的实际可用电话号码。此命令会将电话号码配置到您的帐户。

**Example : 检查电话号码状态**  
订购电话号码后，您可以查看其状态：  

```
# Get the phone number order status
aws chime-sdk-voice get-phone-number-order \
  --phone-number-order-id abcd1234-5678-90ab-cdef-EXAMPLE55555 \
  --region us-east-1
```

将订单编号替换为`create-phone-number-order`命令返回的订单编号。

**Example : 在库存中列出电话号码**  
要查看库存中的所有电话号码，请执行以下操作：  

```
# List all phone numbers
aws chime-sdk-voice list-phone-numbers \
  --region us-east-1
```
要查找可用于 SIP 规则的未分配电话号码，请执行以下操作：  

```
# List unassigned phone numbers
aws chime-sdk-voice list-phone-numbers \
  --region us-east-1 \
  --query "PhoneNumbers[?Status=='Unassigned'].E164PhoneNumber"
```

## 创建用于呼叫处理的 Lambda 函数
<a name="route-calls-events-cli-create-function"></a>

现在，让我们创建一个用于处理来电的 Lambda 函数。该函数将接收来自 PSTN 音频服务的事件，并以如何处理呼叫的说明进行响应。

**Example : 为 Lambda 创建 IAM 角色**  
在创建 Lambda 函数之前，您需要创建一个授予必要权限的 IAM 角色。  

```
cat > lambda-trust-policy.json << EOF
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
EOF
```

```
aws iam create-role --role-name ChimeSDKLambdaRole \
  --assume-role-policy-document file://lambda-trust-policy.json
```

```
aws iam attach-role-policy --role-name ChimeSDKLambdaRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
```
这些命令创建一个 IAM 角色，允许 Lambda 代入该角色并附加基本执行策略，该策略为 Lambda 提供写入日志的权限。 CloudWatch

**Example 创建 Lambda 函数：**  
现在，创建一个用于处理来电的简单 Lambda 函数。  

```
mkdir -p lambda
cat > lambda/index.js << EOF
exports.handler = async (event) => {
  console.log('Received event:', JSON.stringify(event, null, 2));
  
  // Simple call handling logic
  const response = {
    SchemaVersion: '1.0',
    Actions: [
      {
        Type: 'Speak',
        Parameters: {
          Engine: 'neural',
          Text: 'Hello! This is a test call from Amazon Chime SDK PSTN Audio.',
          VoiceId: 'Joanna'
        }
      },
      {
        Type: 'Hangup',
        Parameters: {
          SipResponseCode: '200'
        }
      }
    ]
  };
  
  return response;
};
EOF
```

```
cd lambda
zip -r function.zip index.js
cd ..
```

```
# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

aws lambda create-function \
  --function-name ChimeSDKCallHandler \
  --runtime nodejs18.x \
  --role arn:aws:iam::${ACCOUNT_ID}:role/ChimeSDKLambdaRole \
  --handler index.handler \
  --zip-file fileb://lambda/function.zip
```
此 Lambda 函数用语音消息回应来电，然后挂断电话。

**Example : 为亚马逊 Chime 软件开发工具包添加 Lambda 权限**  
向 Amazon Chime 软件开发工具包服务授予调用您的 Lambda 函数的权限。  

```
# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

aws lambda add-permission \
  --function-name ChimeSDKCallHandler \
  --statement-id ChimeSDK \
  --action lambda:InvokeFunction \
  --principal voiceconnector.chime.amazonaws.com \
  --source-account ${ACCOUNT_ID}
```
此命令允许 Amazon Chime SDK 语音连接器服务调用您的 Lambda 函数。

## 创建 SIP 媒体应用程序
<a name="route-calls-events-cli-create-sip-app"></a>

SIP 媒体应用程序将您的 Lambda 函数连接到 PSTN 音频服务。在本节中，您将创建一个使用您的 Lambda 函数的 SIP 媒体应用程序。

**Example : 创建 SIP 媒体应用程序**  

```
# Get your Lambda function ARN
LAMBDA_ARN=$(aws lambda get-function --function-name ChimeSDKCallHandler --query Configuration.FunctionArn --output text)

aws chime-sdk-voice create-sip-media-application \
  --aws-region us-east-1 \
  --name "MyCallHandlerApp" \
  --endpoints "[{\"LambdaArn\":\"${LAMBDA_ARN}\"}]"
```
SIP 媒体应用程序充当 PSTN 音频服务和您的 Lambda 函数之间的桥梁。

**Example : 获取 SIP 媒体应用程序 ID**  
创建 SIP 媒体应用程序后，您需要检索其 ID 以供本教程的后面部分使用。  

```
SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
  --query "SipMediaApplications[?Name=='MyCallHandlerApp'].SipMediaApplicationId" \
  --output text)

echo "SIP Media Application ID: ${SIP_MEDIA_APP_ID}"
```
记下此命令返回的 SIP 媒体应用程序 ID，因为在创建 SIP 规则时需要它。

## 使用 SIP 规则设置呼叫路由
<a name="route-calls-events-cli-call-routing-sip-rules"></a>

SIP 规则决定如何将来电路由到 SIP 媒体应用程序。您可以根据电话号码或语音连接器主机名创建规则。

**Example : 使用电话号码触发器创建 SIP 规则**  
要根据电话号码路由呼叫，请使用以下命令：  

```
# Get an unassigned phone number from your inventory
PHONE_NUMBER=$(aws chime-sdk-voice list-phone-numbers \
  --query "PhoneNumbers[?Status=='Unassigned'].E164PhoneNumber | [0]" \
  --output text)

# If no unassigned phone number is found, you'll need to provision one
if [ -z "$PHONE_NUMBER" ] || [ "$PHONE_NUMBER" == "None" ]; then
  echo "No unassigned phone numbers found. Please provision a phone number first."
  exit 1
fi

echo "Using phone number: ${PHONE_NUMBER}"

aws chime-sdk-voice create-sip-rule \
  --name "IncomingCallRule" \
  --trigger-type ToPhoneNumber \
  --trigger-value "${PHONE_NUMBER}" \
  --target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1}]"
```
此命令创建一个 SIP 规则，用于将拨打您电话号码的呼叫路由到您的 SIP 媒体应用程序。

**Example : 使用请求 URI 主机名触发器创建 SIP 规则**  
或者，您可以根据传入的语音连接器 SIP 呼叫的请求 URI 来路由呼叫：  

```
# Replace with your Voice Connector hostname
VOICE_CONNECTOR_HOST="example.voiceconnector.chime.aws"

aws chime-sdk-voice create-sip-rule \
  --name "VoiceConnectorRule" \
  --trigger-type RequestUriHostname \
  --trigger-value "${VOICE_CONNECTOR_HOST}" \
  --target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1}]"
```
将主机名替换为语音连接器的出站主机名。

## 使用多个 SIP 媒体应用程序设置冗余
<a name="route-calls-events-cli-sip-redundancy"></a>

为了实现冗余和故障转移，您可以在同一 AWS 区域创建多个 SIP 媒体应用程序并指定其优先顺序。

**Example : 创建备份 Lambda 函数**  
首先，在同一区域创建备份 Lambda 函数。  

```
cat > lambda/backup-index.js >< EOF
exports.handler = async (event) => {
  console.log('Received event in backup handler:', JSON.stringify(event, null, 2));

  // Simple call handling logic for backup
  const response = {
    SchemaVersion: '1.0',
    Actions: [
      {
        Type: 'Speak',
        Parameters: {
          Engine: 'neural',
          Text: 'Hello! This is the backup handler for Amazon Chime SDK PSTN Audio.',
          VoiceId: 'Matthew'
        }
      },
      {
        Type: 'Hangup',
        Parameters: {
          SipResponseCode: '200'
        }
      }
    ]
  };

  return response;
};
EOF
```

```
                    cd lambda
                    zip -r backup-function.zip backup-index.js
                    cd ..
```

```
                    # Get your AWS account ID
                    ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
                    
                    aws lambda create-function \
                    --function-name ChimeSDKBackupHandler \
                    --runtime nodejs18.x \
                    --role arn:aws:iam::${ACCOUNT_ID}:role/ChimeSDKLambdaRole \
                    --handler backup-index.handler \
                    --zip-file fileb://lambda/backup-function.zip
```

**Example : 在备份功能中添加 Amazon Chime 软件开发工具包的 Lambda 权限**  

```
                    # Get your AWS account ID
                    ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
                    
                    aws lambda add-permission \
                    --function-name ChimeSDKBackupHandler \
                    --statement-id ChimeSDK \
                    --action lambda:InvokeFunction \
                    --principal voiceconnector.chime.amazonaws.com \
                    --source-account ${ACCOUNT_ID}
```

**Example : 创建备份 SIP 媒体应用程序**  

```
# Get your backup Lambda function ARN
BACKUP_LAMBDA_ARN=$(aws lambda get-function --function-name ChimeSDKBackupHandler --query Configuration.FunctionArn --output text)

aws chime-sdk-voice create-sip-media-application \
  --aws-region us-east-1 \
  --name "BackupCallHandlerApp" \
  --endpoints "[{\"LambdaArn\":\"${BACKUP_LAMBDA_ARN}\"}]"

# Get the backup SIP media application ID
BACKUP_SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
  --query "SipMediaApplications[?Name=='BackupCallHandlerApp'].SipMediaApplicationId" \
  --output text)
```

**Example : 获取 SIP 规则 ID**  

```
SIP_RULE_ID=$(aws chime-sdk-voice list-sip-rules \
  --query "SipRules[?Name=='IncomingCallRule'].SipRuleId" \
  --output text)
```

**Example : 更新 SIP 规则以包括两个具有优先级的应用程序**  

```
aws chime-sdk-voice update-sip-rule \
  --sip-rule-id ${SIP_RULE_ID} \
  --target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1},{\"SipMediaApplicationId\":\"${BACKUP_SIP_MEDIA_APP_ID}\",\"Priority\":2}]"
```
此命令更新 SIP 规则，使其包括主 SIP 媒体应用程序和备份 SIP 媒体应用程序及其各自的优先级。

## 创建出站呼叫
<a name="route-calls-events-cli-create-outbound"></a>

您还可以使用 API 创建调用您的 Lambda 函数的出站调用。`CreateSIPMediaApplicationCall`

```
# Use a phone number from your inventory for outbound calling
FROM_PHONE_NUMBER=${PHONE_NUMBER}
TO_PHONE_NUMBER="+12065550102"  # Replace with a valid destination number

aws chime-sdk-voice create-sip-media-application-call \
  --from-phone-number "${FROM_PHONE_NUMBER}" \
  --to-phone-number "${TO_PHONE_NUMBER}" \
  --sip-media-application-id ${SIP_MEDIA_APP_ID}
```

将目标电话号码替换为有效的号码。您需要在库存中包含电话号码才能拨打真实电话。

## 在激活的呼叫期间触发 Lambda
<a name="route-calls-events-cli-trigger-lambda"></a>

您可以使用 API 在活动调用期间触发您的 Lambda 函数。`UpdateSIPMediaApplicationCall`

```
# Replace with an actual transaction ID from an active call
TRANSACTION_ID="txn-3ac9de3f-6b5a-4be9-9e7e-EXAMPLE33333"

aws chime-sdk-voice update-sip-media-application-call \
  --sip-media-application-id ${SIP_MEDIA_APP_ID} \
  --transaction-id ${TRANSACTION_ID} \
  --arguments '{"action":"custom-action"}'
```

当调用处于活动状态时，将在发送给您的 Lambda 函数的事件数据中提供交易 ID。

## 清理 资源
<a name="route-calls-events-cli-cleanup-resources"></a>

完成本教程后，应删除自己创建的资源，以免产生额外费用。

**Example : 删除 SIP 规则**  

```
# Get the SIP rule ID if you don't have it
SIP_RULE_ID=$(aws chime-sdk-voice list-sip-rules \
  --query "SipRules[?Name=='IncomingCallRule'].SipRuleId" \
  --output text)

aws chime-sdk-voice delete-sip-rule --sip-rule-id ${SIP_RULE_ID}
```

**Example : 删除 SIP 媒体应用程序**  

```
# Get SIP media application IDs if you don't have them
SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
  --query "SipMediaApplications[?Name=='MyCallHandlerApp'].SipMediaApplicationId" \
  --output text)

BACKUP_SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
  --query "SipMediaApplications[?Name=='BackupCallHandlerApp'].SipMediaApplicationId" \
  --output text)

aws chime-sdk-voice delete-sip-media-application --sip-media-application-id ${SIP_MEDIA_APP_ID}
aws chime-sdk-voice delete-sip-media-application --sip-media-application-id ${BACKUP_SIP_MEDIA_APP_ID}
```

**Example : 删除 Lambda 函数**  

```
aws lambda delete-function --function-name ChimeSDKCallHandler
aws lambda delete-function --function-name ChimeSDKBackupHandler
```

**Example : 删除 IAM 角色**  

```
aws iam detach-role-policy --role-name ChimeSDKLambdaRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

aws iam delete-role --role-name ChimeSDKLambdaRole
```

**Example : 发布电话号码**  
如果您不再需要电话号码，可以将其释放：  

```
# List phone numbers
aws chime-sdk-voice list-phone-numbers

# Delete a specific phone number
aws chime-sdk-voice delete-phone-number --phone-number-id ${PHONE_NUMBER}
```

请注意，电话号码会在 7 天内进入 ReleaseInProgress “” 状态，然后才会完全发布。在此期间，如果需要，您可以使用`restore-phone-number`命令恢复它们。

## 投入生产
<a name="route-calls-events-cli-going-to-production"></a>

本教程演示了使用 Amazon Chime SDK PSTN 音频将调用路由到 Lambda 函数的基本功能。但是，对于生产环境，您应该考虑以下最佳实践：

### 安全注意事项
<a name="route-calls-events-cli-security"></a>
+ 实现最低权限权限。创建仅授予您的 Lambda 函数所需的特定权限的自定义 IAM 策略。
+ 在 Lambda 权限中添加源 ARN 条件。限制哪些 SIP 媒体应用程序可以调用您的 Lambda 函数。
+ 实现输入验证。为您的 Lambda 函数添加验证，确保它们仅处理有效事件。
+ 考虑部署 VPC。为了增强安全性，请在具有相应安全组的 VPC 内部署 Lambda 函数。
+ 加密敏感数据。 AWS Key Management Service 用于加密应用程序使用的任何敏感数据。

### 架构注意事项
<a name="route-calls-events-cli-architecture"></a>
+ 实现监控和日志记录。设置 CloudWatch 警报和日志以监控应用程序的运行状况和性能。
+ 添加错误处理。在您的 Lambda 函数中实现全面的错误处理。
+ 考虑缩放限制。如果呼叫量大，请注意服务配额和请求的增加。
+ 实现基础架构即代码。使用 CloudFormation 或 AWS CDK 来部署您的基础架构。
+ 设置 CI/CD 管道。为您的 Lambda 函数实施持续集成和部署。

有关构建生产就绪应用程序的更多信息，请参阅：
+ [AWS 架构完善的框架](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html) 
+ [安全性、身份和合规性最佳实践](https://aws.amazon.com/architecture/security-identity-compliance/)
+ [无服务器应用程序剖析](https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/welcome.html) 

## 后续步骤
<a name="route-calls-events-cli-next-steps"></a>

现在，您已经学习了如何使用 Amazon Chime SDK PSTN 音频将调用路由到 Lambda 函数，您可以探索更多高级功能：
+ 与 Amazon Lex 集成，以管理智能代理场景的对话交互。有关更多信息，请参阅 [创建用于 Amazon Chime SDK 消息传递的 Amazon Lex V2 机器人](create-lex-bot.md)。
+ 设置语音分析以从您的通话中获取见解。有关更多信息，请参阅 [针对 Amazon Chime SDK 使用呼叫分析从呼叫中生成见解](call-analytics.md)。
+ 探索高级呼叫控制操作以构建复杂的呼叫流程。有关更多信息，请参阅 [针对 Amazon Chime SDK 使用呼叫分析配置](using-call-analytics-configurations.md)。