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

# 將呼叫路由到 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 User Guide* 中的 [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
+  AWS CLI 使用適當的登入資料設定您的 。若尚未設定憑證，請執行 `aws configure`。
+ 基本熟悉 AWS Lambda 和 Amazon Chime SDK 概念。
+ 設定足夠的許可，以在您的 AWS 帳戶中建立和管理 Amazon Chime SDK 和 Lambda 資源。
+ 對於以電話號碼為基礎的轉接，您需要在 Amazon Chime SDK 電話號碼庫存中擁有電話號碼。
+ 對於語音連接器型路由，您需要在帳戶中設定語音連接器。

## 成本考量
<a name="route-calls-events-cli-cost"></a>

本教學課程包含清除說明，以確保您在完成後不會持續產生費用。如需詳細資訊，請參閱 [Amazon Chime SDK 定價](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
```

將訂單 ID 取代為從`create-phone-number-order`命令傳回的訂單 ID。

**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 ：新增 Amazon Chime SDK 的 Lambda 許可**  
將叫用 Lambda 函數的許可授予 Amazon Chime SDK 服務。  

```
# 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 Voice Connector 服務調用 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 媒體應用程式。您可以根據電話號碼或 Voice Connector 主機名稱建立規則。

**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}]"
```
將主機名稱取代為您 Voice Connector 的傳出主機名稱。

## 使用多個 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 SDK 的 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 媒體應用程式包含各自的優先順序。

## 建立外撥通話
<a name="route-calls-events-cli-create-outbound"></a>

您也可以使用 `CreateSIPMediaApplicationCall` API 建立叫用 Lambda 函數的傳出呼叫。

```
# 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>

您可以使用 `UpdateSIPMediaApplicationCall` API 在作用中呼叫期間觸發 Lambda 函數。

```
# 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}
```

請注意，電話號碼會輸入「ReleaseInProgress」狀態 7 天，之後才會完全釋出。在此期間，您可以視需要使用 `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>
+ 實作最低權限許可。建立自訂 IAM 政策，僅授予 Lambda 函數所需的特定許可。
+ 將來源 ARN 條件新增至 Lambda 許可。限制哪些 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 Well-Architected 架構](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)。