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

# 更新 Amazon Chime SDK PTSN 音訊的進行中呼叫
<a name="update-sip-call"></a>

作為 PSTN 音訊服務的一部分，SIP 媒體應用程式可讓您根據通話事件叫用使用者定義的 Lambda 函數，例如來電或 DTMF 數字，來設定在通話上執行的動作。[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 可讓您在呼叫作用中時隨時觸發 Lambda 函數，以呼叫傳回的新動作取代目前的動作。

**工作流程**  
您可以在各種情況下使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API，例如將參與者新增至會議、將使用者靜音和解除靜音、中斷連線等。下列使用案例說明典型的工作流程。

當 Amazon Chime SDK 設定會議時，使用者會呼叫和聆聽音樂。設定完成後，Amazon Chime SDK 會停止音訊，並將發起人加入會議。接著，假設使用個別系統 `MyMeetingService`來管理會議。每個來電都應保留。Chime 會通知 MyMeetingService 有關來電，然後 MyMeetingService 會為每個呼叫建立出席者，當 MyMeetingService 準備好開始會議時，它會通知 SIP 媒體應用程式，並提供加入會議的權杖。

若要處理這種情況，Lambda 函數必須實作下列邏輯。
+ 當新的來電送達時，系統會使用`NEW_INBOUND_CALL`事件叫用 Lambda。Lambda 會呼叫 `MyMeetingService`並傳遞`transactionId`可識別目前呼叫的 ，然後傳回 `PlayAudio`動作。
+ 當 `MyMeetingService` 準備好將發起人新增至會議時，服務會呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 並傳遞呼叫的 `transactionId`和 `JoinToken` 作為其引數的一部分。此 API 呼叫會再次觸發 Lambda 函數，現在使用 `CALL_UPDATE_REQUESTED`事件。MyMeetingService 會將 傳遞`JoinToken`至 Lambda 函數做為事件的一部分，並使用字符將`JoinChimeMeeting`動作傳回至 SIP 媒體應用程式，這會中斷`PlayAudio`動作並將發起人連線至會議。

![顯示 UpdateSipMediaApplicationCall API 中資料流程的圖表。](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/update-sip-call-flow3.png)


**注意**  
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API 會傳回 HTTP 202 （已接受）。SIP 媒體應用程式會確認呼叫正在進行中且可更新，因此會嘗試叫用 Lambda 函數。調用會以非同步方式執行，因此 API 的成功回應並不保證 Lambda 函數已啟動或完成。

下列範例顯示請求語法。

```
{
    "SipMediaApplicationId": "{{string}}",
    "TransactionId": "{{string}}",
    "Arguments": {
        "string": "{{string}}"
    } 
}
```

**請求參數**
+ `SipMediaApplicationId` – 處理呼叫的 SIP 媒體應用程式的 ID。
+ `TransactionId` – 呼叫交易的 ID。對於傳入呼叫，`TransactionId`可以從在第一次調用時傳遞給 Lambda 函數`NEW_INCOMING_CALL`的事件中取得 。對於外撥通話， `TransactionId` 會在 的回應中傳回[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateSipMediaApplicationCall.html)。
+ **引數** – 作為`CallUpdateRequest`動作資料的一部分提供給 Lambda 函數的自訂引數。可以包含 0 到 20 個鍵/值對。

下列範例顯示典型的 請求。

```
aws chime update-sip-media-application-call --sip-media-application-id feb37a7e-2b66-49fb-b2dd-30f4780dc36d --transaction-id 1322a4e7-c106-4e70-aaaf-a8fa4c77c0cb --arguments '{"JoinToken": "{{abc123}}"}'
```

**回應語法**

```
{
  "SipMediaApplicationCall": {
  "TransactionId": "{{string}}"
  }
}
```

**回應元素**
+ **TransactionId** – 呼叫交易的 ID，與請求相同的 ID。

下列範例顯示`CALL_UPDATE_REQUESTED`調用事件。

```
{
  "SchemaVersion": "1.0",
  "Sequence": {{2}},
  "InvocationEventType": "CALL_UPDATE_REQUESTED",
  "ActionData": {
    "Type": "CallUpdateRequest",
    "Parameters": {
      "Arguments": {
        "{{string}}": "{{string}}"
      }
    }
  },
  "CallDetails": {
    ...
  }
}
```

**事件元素**
+ **SchemaVersion** – JSON 結構描述的版本 (1.0)
+ **序列** – 呼叫中事件的序號
+ **InvocationEventType** – Lambda 調用事件的類型，在此情況下， `CALL_UPDATE_REQUESTED`
+ **ActionData** – 與`CallUpdateRequest`動作相關聯的資料。
  + **類型** – 動作類型，在此情況下， `CallUpdateRequest`
  + **參數** – 動作的參數
    + **引數** – 做為 `UpdateSipMediaApplicationCall` API 請求的一部分傳遞的引數
+ **CallDetails** – 目前呼叫狀態的相關資訊

**了解可中斷和不可中斷的動作**  
當 Lambda 函數在現有動作執行時傳回動作的新清單時，所有追蹤進行中動作的動作都會取代為新的動作。在某些情況下，Lambda 函數會中斷進行中的動作，以立即執行新的動作。

下圖顯示典型的範例。圖表下方的文字說明邏輯。

![顯示如何在進行中的 SIP 媒體應用程式呼叫期間取代動作的圖表。](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/update-sip-actions.png)


如果動作 2 可中斷，我們會停止它並改為執行新的動作 1。

如果動作 2 無法中斷，它會在新的動作 1 啟動之前完成。

在這兩種情況下，動作 3 都不會執行。

如果某個動作中斷，則會使用 `ACTION_INTERRUPTED`事件叫用 Lambda 函數。此事件僅用於資訊用途。SIP 媒體應用程式會忽略此調用傳回的所有動作。

可中斷動作的類型：
+ `PlayAudio`
+ `RecordAudio`
+ `Pause`

**Lambda 函數範例**  
此範例顯示典型的 Lambda 函數，可播放音訊檔案、傳遞聯結字符，以及更新呼叫。

```
const MMS = require('my-meeting-service');
const myMeetingServiceClient = new MMS.Client();

exports.handler = async (event) => {
    console.log('Request: ' + JSON.stringify(event));
    
    const playAudio = () => {
      return {
        Type: 'PlayAudio',
        Parameters: {
          ParticipantTag: 'LEG-A',
          AudioSource: {
            Type: 'S3',
            BucketName: '{{chime-meetings-audio-files-bucket-name}}',
            Key: '{{welcome.wav}}'
          }
        }
      }
    }
    
    const joinChimeMeeting = (joinToken) => {
      return {
        Type: 'JoinChimeMeeting',
        Parameters: {
          JoinToken: {{joinToken}}
        }
      }
    }
    
    const response = (...actions) => {
      const r = {
        SchemaVersion: '1.0',
        Actions: actions
      };
      console.log('Response: ' + JSON.stringify(r));
      return r;
    };
    
    switch (event.InvocationEventType) {
      case 'NEW_INBOUND_CALL': 
        myMeetingServiceClient.addPendingCall(event.CallDetails.TransactionId);         
        return response(playAudio());      
      case 'CALL_UPDATE_REQUESTED':
        const joinToken = event.ActionData.Parameters.Arguments['{{JoinToken}}']
        return response(joinChimeMeeting(joinToken));
      default:
        return response();
    }
}
```