共用方式為


通話錄音快速入門

本快速入門可讓您開始使用語音和視訊通話的通話錄音。 若要開始使用通話錄音 API,您必須有通話發生。 請確定您已熟悉通話用戶端 SDK 和/或通話自動化,以建置終端使用者通話體驗。

範例程式碼

您可以從 GitHub 下載範例應用程式

必要條件

  • 您需要具有有效訂用帳戶的 Azure 帳戶。
  • 部署通訊服務資源。 記錄您的資源連接字串
  • 透過 Azure 事件方格訂閱事件。
  • 下載 .NET SDK

在您開始使用 Intune 之前

通話錄音 API 只使用 serverCallId 來起始錄製。 根據您的案例,您可以使用幾種方法來擷取 serverCallId

通話自動化案例

  • 使用通話自動化時,您有兩個選項可取得 serverCallId
    1. 一旦建立通話,系統會在建立通話之後,傳回 serverCallId 作為 CallConnected 事件的屬性。 了解如何從通話自動化 SDK 取得 CallConnected 事件
    2. 一旦您接聽來電或是已建立通話,系統會傳回 serverCallId 分別作為 AnswerCallResultCreateCallResult API 回應的屬性。

通話 SDK 案例

  • 使用通話用戶端 SDK 時,您可以藉由在通話上使用 getServerCallId 方法來擷取 serverCallId。 使用此範例以了解如何從通話用戶端 SDK 取得 serverCallId

讓我們從一些簡單的步驟開始!

1.建立通話自動化用戶端

通話錄音 API 是 Azure 通訊服務呼叫自動化程式庫的一部分。 因此,您必須建立通話自動化用戶端。 若要建立通話自動化用戶端,您可以使用通訊服務連接字串,並將其傳遞至 CallAutomationClient 物件。

CallAutomationClient callAutomationClient = new CallAutomationClient("<ACSConnectionString>");

2.使用 'StartAsync' API 透過 StartRecordingOptions 開始錄製工作階段

使用在通話起始期間接收的 serverCallId

  • RecordingContent 是用來傳遞錄製內容類型。 使用音訊
  • RecordingChannel 是用來傳遞錄製頻道類型。 使用混合或原音。
  • RecordingFormat 是用來傳遞錄製的格式。 使用 wav。
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>")) 
{
    RecordingContent = RecordingContent.Audio,
    RecordingChannel = RecordingChannel.Unmixed,
    RecordingFormat = RecordingFormat.Wav,
    RecordingStateCallbackUri = new Uri("<CallbackUri>");
};
Response<RecordingStateResult> response = await callAutomationClient.GetCallRecording()
.StartAsync(recordingOptions);

2.1. 開始錄製 - 自備 Azure Blob 存放區

使用您自己定義的 Azure Blob 儲存體 開始錄製,以在錄製完成後儲存錄製檔案。

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>"))
{
   RecordingContent = RecordingContent.Audio,
   RecordingChannel = RecordingChannel.Unmixed,
   RecordingFormat = RecordingFormat.Wav,
   RecordingStateCallbackUri = new Uri("<CallbackUri>"),
   RecordingStorage = RecordingStorage.CreateAzureBlobContainerRecordingStorage(new Uri("<YOUR_STORAGE_CONTAINER_URL>"))
};
Response<RecordingStateResult> response = await callAutomationClient.GetCallRecording()
.StartAsync(recordingOptions);

2.2. 使用 『StartAsync』 API 啟用暫停模式的開始錄製工作階段

注意

必須繼續錄製,才能產生錄製檔案。

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>")) 
{
    RecordingContent = RecordingContent.Audio,
    RecordingChannel = RecordingChannel.Unmixed,
    RecordingFormat = RecordingFormat.Wav,
    PauseOnStart = true,
    RecordingStateCallbackUri = new Uri("<CallbackUri>");
};
Response<RecordingStateResult> response = await callAutomationClient.GetCallRecording()
.StartAsync(recordingOptions);

2.3. 僅適用於原音 - 在頻道 0 上指定使用者

若要產生原音音訊錄製檔案,您可以使用 AudioChannelParticipantOrdering 功能來指定要在頻道 0 上錄製的使用者。 其餘參與者會在說話時指派給頻道。 如果您使用 RecordingChannel.Unmixed 但未使用 AudioChannelParticipantOrdering,通話錄音會將頻道 0 指派給第一個說話的參與者。

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>")) 
{
    RecordingContent = RecordingContent.Audio,
    RecordingChannel = RecordingChannel.Unmixed,
    RecordingFormat = RecordingFormat.Wav,
    RecordingStateCallbackUri = new Uri("<CallbackUri>"),
    AudioChannelParticipantOrdering = { new CommunicationUserIdentifier("<ACS_USER_MRI>") }
    
};
Response<RecordingStateResult> response = await callAutomationClient.GetCallRecording().StartAsync(recordingOptions);

2.4. 僅適用於原音 - 指定頻道親和性

var channelAffinity = new ChannelAffinity(new CommunicationUserIdentifier("<ACS_USER_MRI>")) { Channel = 0};
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>"))
{
   RecordingContent = RecordingContent.Audio,
   RecordingChannel = RecordingChannel.Unmixed,
   RecordingFormat = RecordingFormat.Wav,
   RecordingStateCallbackUri = new Uri("<CallbackUri>"),
   ChannelAffinity = new List<ChannelAffinity>{ channelAffinity }
};
Response<RecordingStateResult> response = await callAutomationClient.GetCallRecording().StartAsync(recordingOptions);

StartAsync API 回應包含錄製工作階段的 recordingId

3.使用 'StopAsync' API 停止錄製工作階段

使用在 StartAsync 的回應中接收的 recordingId

var stopRecording = await callAutomationClient.GetCallRecording().StopAsync(recordingId);

4.使用 'PauseAsync' API 暫停錄製工作階段

使用在 StartAsync 的回應中接收的 recordingId

var pauseRecording = await callAutomationClient.GetCallRecording ().PauseAsync(recordingId);

5.使用 'ResumeAsync' API 繼續錄製工作階段

使用在 StartAsync 的回應中接收的 recordingId

var resumeRecording = await callAutomationClient.GetCallRecording().ResumeAsync(recordingId);

6.使用 'DownloadToAsync' API 下載錄製檔案

使用 Azure 事件方格 Webhook,或者應該使用其他已觸發動作,在錄製媒體準備好可供下載時通知您的服務。

錄製內容可供擷取時會發佈事件方格通知 Microsoft.Communication.RecordingFileStatusUpdated,通常在錄製程序完成後的幾分鐘 (例如會議結束、錄製停止)。 錄製事件通知包括 contentLocationmetadataLocation,用於擷取錄製的媒體和中繼資料錄製檔案。

事件結構描述的範例:

{
    "id": string, // Unique guid for event
    "topic": string, // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
    "subject": string, // /recording/call/{call-id}/serverCallId/{serverCallId}
    "data": {
        "recordingStorageInfo": {
            "recordingChunks": [
                {
                    "documentId": string, // Document id for the recording chunk
                    "contentLocation": string, //Azure Communication Services URL where the content is located
                    "metadataLocation": string, // Azure Communication Services URL where the metadata for this chunk is located
                    "deleteLocation": string, // Azure Communication Services URL to use to delete all content, including recording and metadata.
                    "index": int, // Index providing ordering for this chunk in the entire recording
                    "endReason": string, // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
                }
            ]
        },
        "recordingStartTime": string, // ISO 8601 date time for the start of the recording
        "recordingDurationMs": int, // Duration of recording in milliseconds
        "sessionEndReason": string // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
    },
    "eventType": string, // "Microsoft.Communication.RecordingFileStatusUpdated"
    "dataVersion": string, // "1.0"
    "metadataVersion": string, // "1"
    "eventTime": string // ISO 8601 date time for when the event was created
}

使用 DownloadToAsync API 來下載錄製媒體。

var recordingDownloadUri = new Uri(contentLocation);
var response = await callAutomationClient.GetCallRecording().DownloadToAsync(recordingDownloadUri, fileName);

錄製的 downloadLocation 可以從 recordingChunkcontentLocation 屬性擷取。 DownloadToAsync 方法會將內容下載至提供的檔案名稱。

7.使用 'DeleteAsync' API 刪除錄製內容

使用 DeleteAsync API 來刪除錄製內容 (例如,錄製媒體、中繼資料)

var recordingDeleteUri = new Uri(deleteLocation);
var response = await callAutomationClient.GetCallRecording().DeleteAsync(recordingDeleteUri);

範例程式碼

您可以從 GitHub 下載範例應用程式

必要條件

  • 您需要具有有效訂用帳戶的 Azure 帳戶。
  • 部署通訊服務資源。 記錄您的資源連接字串
  • 透過 Azure 事件方格訂閱事件。
  • 下載 JAVA SDK

在您開始使用 Intune 之前

通話錄音 API 只使用 serverCallId 來起始錄製。 根據您的案例,您可以使用幾種方法來擷取 serverCallId

通話自動化案例

  • 使用通話自動化時,您有兩個選項可取得 serverCallId
    1. 一旦建立通話,系統會在建立通話之後,傳回 serverCallId 作為 CallConnected 事件的屬性。 了解如何從通話自動化 SDK 取得 CallConnected 事件
    2. 一旦您接聽來電或是已建立通話,系統會傳回 serverCallId 分別作為 AnswerCallResultCreateCallResult API 回應的屬性。

通話 SDK 案例

  • 使用通話用戶端 SDK 時,您可以藉由在通話上使用 getServerCallId 方法來擷取 serverCallId。 使用此範例以了解如何從通話用戶端 SDK 取得 serverCallId

讓我們從一些簡單的步驟開始!

1.建立通話自動化用戶端

通話錄音 API 是 Azure 通訊服務呼叫自動化程式庫的一部分。 因此,您必須建立通話自動化用戶端。 若要建立通話自動化用戶端,您可以使用通訊服務連接字串,並將其傳遞至 CallAutomationClient 物件。

CallAutomationClient callAutomationClient = new CallAutomationClientBuilder()
            .connectionString("<acsConnectionString>")
            .buildClient();

2.使用 'startWithResponse' API 透過 StartRecordingOptions 開始錄製工作階段

使用在通話起始期間接收的 serverCallId

  • RecordingContent 是用來傳遞錄製內容類型。 使用 AUDIO
  • RecordingChannel 是用來傳遞錄製頻道類型。 使用混合或原音。
  • RecordingFormat 是用來傳遞錄製的格式。 使用 WAV。
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
                    .setRecordingChannel(RecordingChannel.UNMIXED)
                    .setRecordingFormat(RecordingFormat.WAV)
                    .setRecordingContent(RecordingContent.AUDIO)
                    .setRecordingStateCallbackUrl("<recordingStateCallbackUrl>");

Response<RecordingStateResult> response = callAutomationClient.getCallRecording()
.startWithResponse(recordingOptions, null);

2.1. 開始錄製 - 自備 Azure Blob 存放區

使用您自己的 Azure Blob 儲存體 啟動錄製工作階段,以在錄製完成後儲存錄製檔案。

       StartRecordingOptions recordingOptions = new StartRecordingOptions(callLocator)
       .setRecordingChannel(RecordingChannel.MIXED)
       .setRecordingContent(RecordingContent.AUDIO_VIDEO)
       .setRecordingFormat(RecordingFormat.MP4)
       .setRecordingStorage(new AzureBlobContainerRecordingStorage("<YOUR_STORAGE_CONTAINER_URL>"));
 
       // //start recording
       RecordingStateResult result = callRecording.start(recordingOptions);

2.2. 使用 『StartAsync』 API 啟用暫停模式的開始錄製工作階段

注意

必須繼續錄製,才能產生錄製檔案。

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
                    .setRecordingChannel(RecordingChannel.UNMIXED)
                    .setRecordingFormat(RecordingFormat.WAV)
                    .setRecordingContent(RecordingContent.AUDIO)
                    .setRecordingStateCallbackUrl("<recordingStateCallbackUrl>")
                    .setPauseOnStart(true)
                    .setAudioChannelParticipantOrdering(List.of(new CommunicationUserIdentifier("<participantMri>")));

Response<RecordingStateResult> response = callAutomationClient.getCallRecording()
.startWithResponse(recordingOptions, null);

2.3. 僅適用於原音 - 在頻道 0 上指定使用者

若要產生原音音訊錄製檔案,您可以使用 AudioChannelParticipantOrdering 功能來指定要在頻道 0 上錄製的使用者。 其餘參與者會在說話時指派給頻道。 如果您使用 RecordingChannel.Unmixed 但未使用 AudioChannelParticipantOrdering,通話錄音會將頻道 0 指派給第一個說話的參與者。

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
                    .setRecordingChannel(RecordingChannel.UNMIXED)
                    .setRecordingFormat(RecordingFormat.WAV)
                    .setRecordingContent(RecordingContent.AUDIO)
                    .setRecordingStateCallbackUrl("<recordingStateCallbackUrl>")
                    .setAudioChannelParticipantOrdering(List.of(new CommunicationUserIdentifier("<participantMri>")));

Response<RecordingStateResult> response = callAutomationClient.getCallRecording()
.startWithResponse(recordingOptions, null);

2.4. 僅適用於原音 - 指定頻道親和性

ChannelAffinity channelAffinity = new ChannelAffinity()
.setParticipant(new PhoneNumberIdentifier("RECORDING_ID"))
.setChannel(0);
List<ChannelAffinity> channelAffinities = Arrays.asList(channelAffinity);

StartRecordingOptions startRecordingOptions = new StartRecordingOptions(new ServerCallLocator(SERVER_CALL_ID))
   .setRecordingChannel(RecordingChannel.UNMIXED)
   .setRecordingFormat(RecordingFormat.WAV)
   .setRecordingContent(RecordingContent.AUDIO)
   .setRecordingStateCallbackUrl("<recordingStateCallbackUrl>")
   .setChannelAffinity(channelAffinities);
Response<RecordingStateResult> response = callAutomationClient.getCallRecording()
.startRecordingWithResponse(recordingOptions, null);

startWithResponse API 回應包含錄製工作階段的 recordingId

3.使用 'stopWithResponse' API 停止錄製工作階段

使用在 startWithResponse 的回應中接收的 recordingId

Response<Void> response = callAutomationClient.getCallRecording()
               .stopWithResponse(response.getValue().getRecordingId(), null);

4.使用 'pauseWithResponse' API 暫停錄製工作階段

使用在 startWithResponse 的回應中接收的 recordingId

Response<Void> response = callAutomationClient.getCallRecording()
              .pauseWithResponse(response.getValue().getRecordingId(), null);

5.使用 'resumeWithResponse' API 繼續錄製工作階段

使用在 startWithResponse 的回應中接收的 recordingId

Response<Void> response = callAutomationClient.getCallRecording()
               .resumeWithResponse(response.getValue().getRecordingId(), null);

6.使用 'downloadToWithResponse' API 下載錄製檔案

使用 Azure 事件方格 Webhook,或者應該使用其他已觸發動作,在錄製媒體準備好可供下載時通知您的服務。

錄製內容可供擷取時會發佈事件方格通知 Microsoft.Communication.RecordingFileStatusUpdated,通常在錄製程序完成後的幾分鐘 (例如會議結束、錄製停止)。 錄製事件通知包括 contentLocationmetadataLocation,用於擷取錄製的媒體和中繼資料錄製檔案。

以下是事件結構描述的範例。

{
    "id": string, // Unique guid for event
    "topic": string, // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
    "subject": string, // /recording/call/{call-id}/serverCallId/{serverCallId}
    "data": {
        "recordingStorageInfo": {
            "recordingChunks": [
                {
                    "documentId": string, // Document id for the recording chunk
                    "contentLocation": string, //Azure Communication Services URL where the content is located
                    "metadataLocation": string, // Azure Communication Services URL where the metadata for this chunk is located
                    "deleteLocation": string, // Azure Communication Services URL to use to delete all content, including recording and metadata.
                    "index": int, // Index providing ordering for this chunk in the entire recording
                    "endReason": string, // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
                }
            ]
        },
        "recordingStartTime": string, // ISO 8601 date time for the start of the recording
        "recordingDurationMs": int, // Duration of recording in milliseconds
        "sessionEndReason": string // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
    },
    "eventType": string, // "Microsoft.Communication.RecordingFileStatusUpdated"
    "dataVersion": string, // "1.0"
    "metadataVersion": string, // "1"
    "eventTime": string // ISO 8601 date time for when the event was created
}

使用 CallRecording 類別的 downloadToWithResponse 方法來下載錄製媒體。 以下是 downloadToWithResponse 方法支援的參數:

  • contentLocation:內容所在的 Azure 通訊服務 URL。
  • destinationPath:檔案位置。
  • parallelDownloadOptions:選擇性 ParallelDownloadOptions 物件,用來修改平行下載的運作方式。
  • overwrite:True 則會覆寫檔案 (如果檔案存在)。
  • context:代表要求內容的內容。
Boolean overwrite = true;
ParallelDownloadOptions parallelDownloadOptions = null;
Context context = null;

String filePath = String.format(".\\%s.%s", documentId, fileType);
Path destinationPath = Paths.get(filePath);

Response<Void> downloadResponse = callAutomationClient.getCallRecording().downloadToWithResponse(contentLocation, destinationPath, parallelDownloadOptions, overwrite, context);

針對每個 recordingChunk,錄製檔案的內容位置和文件識別碼可以分別從 contentLocationdocumentId 欄位擷取。

7.使用 'deleteWithResponse' API 刪除錄製內容。

使用 CallRecording 類別的 deleteWithResponse 方法來刪除錄製媒體。 以下是 deleteWithResponse 方法支援的參數:

  • deleteLocation:要刪除的內容所在的 Azure 通訊服務 URL。
  • context:代表要求內容的內容。
Response<Void> deleteResponse = callAutomationClient.getCallRecording().deleteWithResponse(deleteLocation, context);

錄製內容的刪除位置可以從事件方格事件的 deleteLocation 欄位擷取。

範例程式碼

您可以從 GitHub 下載範例應用程式

必要條件

  • 您需要具有有效訂用帳戶的 Azure 帳戶。
  • 部署通訊服務資源。 記錄您的資源連接字串
  • 透過 Azure 事件方格訂閱事件。
  • Python 3.7+。

在您開始使用 Intune 之前

通話錄音 API 只使用 serverCallId 來起始錄製。 根據您的案例,您可以使用幾種方法來擷取 serverCallId

通話自動化案例

  • 使用通話自動化時,您有兩個選項可取得 serverCallId
    1. 一旦建立通話,系統會在建立通話之後,傳回 serverCallId 作為 CallConnected 事件的屬性。 了解如何從通話自動化 SDK 取得 CallConnected 事件
    2. 一旦您接聽來電或是已建立通話,系統會傳回 serverCallId 分別作為 AnswerCallResultCreateCallResult API 回應的屬性。

通話 SDK 案例

  • 使用通話用戶端 SDK 時,您可以藉由在通話上使用 server_call_id 變數來擷取 serverCallId。 使用此範例以了解如何從通話用戶端 SDK 取得 serverCallId

讓我們從一些簡單的步驟開始!

1.建立通話自動化用戶端

通話錄音 API 是 Azure 通訊服務呼叫自動化程式庫的一部分。 因此,您必須建立通話自動化用戶端。 若要建立通話自動化用戶端,您可以使用通訊服務連接字串,並將其傳遞至 CallAutomationClient 物件。

call_automation_client = CallAutomationClient.from_connection_string("<ACSConnectionString>")

2.開始錄製工作階段 start_recording API

使用在通話起始期間接收的 serverCallId

  • RecordingContent 是用來傳遞錄製內容類型。 使用音訊
  • RecordingChannel 是用來傳遞錄製頻道類型。 使用混合或原音。
  • RecordingFormat 是用來傳遞錄製的格式。 使用 wav。
response = call_automation_client.start_recording(call_locator=ServerCallLocator(server_call_id),
            recording_content_type = RecordingContent.Audio,
            recording_channel_type = RecordingChannel.Unmixed,
            recording_format_type = RecordingFormat.Wav,
            recording_state_callback_url = "<CallbackUri>")

2.1. 開始錄製 - 自備 Azure Blob 存放區

使用您自己定義的 Azure Blob 儲存體 開始錄製,以在錄製完成後儲存錄製檔案。

response = call_automation_client.start_recording(call_locator=ServerCallLocator(server_call_id),
                   recording_content_type = RecordingContent.Audio,
                   recording_channel_type = RecordingChannel.Unmixed,
                   recording_format_type = RecordingFormat.Wav,
                   recording_state_callback_url = "<CallbackUri>",
                   recording_storage = AzureBlobContainerRecordingStorage(container_url="<YOUR_STORAGE_CONTAINER_URL>"))

2.2. 使用 『StartAsync』 API 啟用暫停模式的開始錄製工作階段

注意

必須繼續錄製,才能產生錄製檔案。

response = call_automation_client.start_recording(call_locator=ServerCallLocator(server_call_id),
            recording_content_type = RecordingContent.Audio,
            recording_channel_type = RecordingChannel.Unmixed,
            recording_format_type = RecordingFormat.Wav,
            pause_on_start = true,
            recording_state_callback_url = "<CallbackUri>")

2.3. 僅適用於原音 - 在頻道 0 上指定使用者

若要產生原音音訊錄製檔案,您可以使用 AudioChannelParticipantOrdering 功能來指定要在頻道 0 上錄製的使用者。 其餘參與者會在說話時指派給頻道。 如果您使用 RecordingChannel.Unmixed 但未使用 AudioChannelParticipantOrdering,通話錄音會將頻道 0 指派給第一個說話的參與者。

response =  call_automation_client.start_recording(call_locator=ServerCallLocator(server_call_id),
            recording_content_type = RecordingContent.Audio,
            recording_channel_type = RecordingChannel.Unmixed,
            recording_format_type = RecordingFormat.Wav,
            recording_state_callback_url = "<CallbackUri>",
            audio_channel_participant_ordering=[CommunicationUserIdentifier(id="<ACS_USER_MRI>")])

2.4. 僅適用於原音 - 指定頻道親和性

_channel_affinity = ChannelAffinity(target_participant=CommunicationUserIdentifier("<ACS_USER_MRI>"), channel=0)

response =  call_automation_client.start_recording(call_locator=ServerCallLocator(server_call_id),
            recording_content_type = RecordingContent.Audio,
            recording_channel_type = RecordingChannel.Unmixed,
            recording_format_type = RecordingFormat.Wav,
            recording_state_callback_url = "<CallbackUri>",
            channel_affinity=[_channel_affinity])

StartAsync API 回應包含錄製工作階段的 recordingId

3.使用 'stop_recording' API 停止錄製工作階段

使用在 start_recording 的回應中接收的 recording_id

stop_recording = call_automation_client.stop_recording(recording_id = recording_id)

4.使用 'pause_recording' API 暫停錄製工作階段

使用在 start_recording 的回應中接收的 recording_id

pause_recording = call_automation_client.pause_recording(recording_id = recording_id)

5.使用 'resume_recording' API 繼續錄製工作階段

使用在 start_recording 的回應中接收的 recording_id

resume_recording = call_automation_client.resume_recording(recording_id = recording_id)

6.使用 'download_recording' API 下載錄製檔案

使用 Azure 事件方格 Webhook,或者應該使用其他已觸發動作,在錄製媒體準備好可供下載時通知您的服務。

錄製內容可供擷取時會發佈事件方格通知 Microsoft.Communication.RecordingFileStatusUpdated,通常在錄製程序完成後的幾分鐘 (例如會議結束、錄製停止)。 錄製事件通知包括 contentLocationmetadataLocation,用於擷取錄製的媒體和中繼資料錄製檔案。

以下是事件結構描述的範例。

{
    "id": string, // Unique guid for event
    "topic": string, // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
    "subject": string, // /recording/call/{call-id}/serverCallId/{serverCallId}
    "data": {
        "recordingStorageInfo": {
            "recordingChunks": [
                {
                    "documentId": string, // Document id for the recording chunk
                    "contentLocation": string, //Azure Communication Services URL where the content is located
                    "metadataLocation": string, // Azure Communication Services URL where the metadata for this chunk is located
                    "deleteLocation": string, // Azure Communication Services URL to use to delete all content, including recording and metadata.
                    "index": int, // Index providing ordering for this chunk in the entire recording
                    "endReason": string, // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
                }
            ]
        },
        "recordingStartTime": string, // ISO 8601 date time for the start of the recording
        "recordingDurationMs": int, // Duration of recording in milliseconds
        "sessionEndReason": string // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
    },
    "eventType": string, // "Microsoft.Communication.RecordingFileStatusUpdated"
    "dataVersion": string, // "1.0"
    "metadataVersion": string, // "1"
    "eventTime": string // ISO 8601 date time for when the event was created
}

使用 download_recording API 來下載錄製媒體。

response = recording_data = call_automation_client.download_recording(content_location)

with open("<file_name>", "wb") as binary_file:
    binary_file.write(recording_data.read())

錄製的 downloadLocation 可以從 recordingChunkcontentLocation 屬性擷取。 download_recording 方法會將內容下載到位元組。

7.使用 'delete_recording' API 刪除錄製內容

使用 delete_recording API 來刪除錄製內容 (例如,錄製媒體、中繼資料)

response = call_automation_client.delete_recording(delete_location);

範例程式碼

您可以從 GitHub 下載範例應用程式

必要條件

  • 您需要具有有效訂用帳戶的 Azure 帳戶。
  • 部署通訊服務資源。 記錄您的資源連接字串
  • 透過 Azure 事件方格訂閱事件。
  • Node.js 作用中 LTS 和為些 LTS 版本 (建議使用 8.11.1 和 10.14.1)

在您開始使用 Intune 之前

通話錄音 API 只使用 serverCallId 來起始錄製。 根據您的案例,您可以使用幾種方法來擷取 serverCallId

通話自動化案例

  • 使用通話自動化時,您有兩個選項可取得 serverCallId
    1. 一旦建立通話,系統會在建立通話之後,傳回 serverCallId 作為 CallConnected 事件的屬性。 了解如何從通話自動化 SDK 取得 CallConnected 事件
    2. 一旦您接聽來電或是已建立通話,系統會傳回 serverCallId 分別作為 AnswerCallResultCreateCallResult API 回應的屬性。

通話 SDK 案例

  • 使用通話用戶端 SDK 時,您可以藉由在通話上使用 getServerCallId 方法來擷取 serverCallId。 使用此範例以了解如何從通話用戶端 SDK 取得 serverCallId

讓我們從一些簡單的步驟開始!

1.建立通話自動化用戶端

通話錄音 API 是 Azure 通訊服務呼叫自動化程式庫的一部分。 因此,您必須建立通話自動化用戶端。 若要建立通話自動化用戶端,您可以使用通訊服務連接字串,並將其傳遞至 CallAutomationClient 物件。

const callAutomationClient = new CallAutomationClient.CallAutomationClient("<ACSConnectionString>");

2.使用 'StartAsync' API 透過 StartRecordingOptions 開始錄製工作階段

使用在通話起始期間接收的 serverCallId

  • RecordingContent 是用來傳遞錄製內容類型。 使用音訊
  • RecordingChannel 是用來傳遞錄製頻道類型。 使用混合或原音。
  • RecordingFormat 是用來傳遞錄製的格式。 使用 wav。
var locator: CallLocator = { id: "<ServerCallId>", kind: "serverCallLocator" };

var options: StartRecordingOptions =
{
  callLocator: locator,
  recordingContent: "audio",
  recordingChannel:"unmixed",
  recordingFormat: "wav",
  recordingStateCallbackEndpointUrl: "<CallbackUri>"
};
var response = await callAutomationClient.getCallRecording().start(options);

2.1. 開始錄製 - 自備 Azure Blob 存放區

使用您自己定義的 Azure Blob 儲存體 開始錄製,以在錄製完成後儲存錄製檔案。

const recordingStorageKind: RecordingStorageKind = "azureBlobStorage"
const recordingStorage: RecordingStorage = { 
       recordingStorageKind: recordingStorageKind, 
       recordingDestinationContainerUrl: "<YOUR_STORAGE_CONTAINER_URL>"
   }
var options: StartRecordingOptions = {
       callLocator: callLocator,
       recordingContent: "audio",
       recordingChannel:"unmixed",
       recordingFormat: "wav",
       recordingStateCallbackEndpointUrl: "<CallbackUri>",
       recordingStorage: recordingStorage
   };
var response = await callAutomationClient.getCallRecording().start(options);

2.2. 使用 『StartAsync』 API 啟用暫停模式的開始錄製工作階段

注意

必須繼續錄製,才能產生錄製檔案。

var locator: CallLocator = { id: "<ServerCallId>", kind: "serverCallLocator" };

var options: StartRecordingOptions =
{
  callLocator: locator,
  recordingContent: "audio",
  recordingChannel:"unmixed",
  recordingFormat: "wav",
  pauseOnStart: true
  recordingStateCallbackEndpointUrl: "<CallbackUri>",
  audioChannelParticipantOrdering:[{communicationUserId: "<ACS_USER_MRI>"}]
};
var response = await callAutomationClient.getCallRecording().start(options);

2.3. 僅適用於原音 - 在頻道 0 上指定使用者

若要產生原音音訊錄製檔案,您可以使用 AudioChannelParticipantOrdering 功能來指定要在頻道 0 上錄製的使用者。 其餘參與者會在說話時指派給頻道。 如果您使用 RecordingChannel.Unmixed 但未使用 AudioChannelParticipantOrdering,通話錄音會將頻道 0 指派給第一個說話的參與者。

var locator: CallLocator = { id: "<ServerCallId>", kind: "serverCallLocator" };

var options: StartRecordingOptions =
{
  callLocator: locator,
  recordingContent: "audio",
  recordingChannel:"unmixed",
  recordingFormat: "wav",
  recordingStateCallbackEndpointUrl: "<CallbackUri>",
  audioChannelParticipantOrdering:[{communicationUserId: "<ACS_USER_MRI>"}]
};
var response = await callAutomationClient.getCallRecording().start(options);

2.4. 僅適用於原音 - 指定頻道親和性

var options: StartRecordingOptions =
{
  callLocator: locator,
  recordingContent: "audio",
  recordingChannel:"unmixed",
  recordingFormat: "wav",
  recordingStateCallbackEndpointUrl: "<CallbackUri>",
  ChannelAffinity:
  [
    {
      channel:0,
      targetParticipant:{communicationUserId: "<ACS_USER_MRI>"}
    }
  ]
};
var response = await callAutomationClient.getCallRecording().start(options);

StartAsync API 回應包含錄製工作階段的 recordingId

3.使用 'stop' API 停止錄製工作階段

使用在 start 的回應中接收的 recordingId

var stopRecording = await callAutomationClient.getCallRecording().stop(recordingId);

4.使用 'pause' API 暫停錄製工作階段

使用在 start 的回應中接收的 recordingId

var pauseRecording = await callAutomationClient.getCallRecording().pause(recordingId);

5.使用 'ResumeAsync' API 繼續錄製工作階段

使用在 start 的回應中接收的 recordingId

var resumeRecording = await callAutomationClient.getCallRecording().resume(recordingId);

6.使用 'DownloadToAsync' API 下載錄製檔案

使用 Azure 事件方格 Webhook,或者應該使用其他已觸發動作,在錄製媒體準備好可供下載時通知您的服務。

錄製內容可供擷取時會發佈事件方格通知 Microsoft.Communication.RecordingFileStatusUpdated,通常在錄製程序完成後的幾分鐘 (例如會議結束、錄製停止)。 錄製事件通知包括 contentLocationmetadataLocation,用於擷取錄製的媒體和中繼資料錄製檔案。

以下是事件結構描述的範例。

{
    "id": string, // Unique guid for event
    "topic": string, // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
    "subject": string, // /recording/call/{call-id}/serverCallId/{serverCallId}
    "data": {
        "recordingStorageInfo": {
            "recordingChunks": [
                {
                    "documentId": string, // Document id for the recording chunk
                    "contentLocation": string, //Azure Communication Services URL where the content is located
                    "metadataLocation": string, // Azure Communication Services URL where the metadata for this chunk is located
                    "deleteLocation": string, // Azure Communication Services URL to use to delete all content, including recording and metadata.
                    "index": int, // Index providing ordering for this chunk in the entire recording
                    "endReason": string, // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
                }
            ]
        },
        "recordingStartTime": string, // ISO 8601 date time for the start of the recording
        "recordingDurationMs": int, // Duration of recording in milliseconds
        "sessionEndReason": string // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
    },
    "eventType": string, // "Microsoft.Communication.RecordingFileStatusUpdated"
    "dataVersion": string, // "1.0"
    "metadataVersion": string, // "1"
    "eventTime": string // ISO 8601 date time for when the event was created
}

使用 downloadToPath API 來下載錄製媒體。

var response = await callAutomationClient.getCallRecording().downloadToPath(contentLocation, fileName);

錄製的 downloadLocation 可以從 recordingChunkcontentLocation 屬性擷取。 DownloadToAsync 方法會將內容下載至提供的檔案名稱。

7.使用 'DeleteAsync' API 刪除錄製內容

使用 delete API 來刪除錄製內容 (例如,錄製媒體、中繼資料)

var response = await callAutomationClient.getCallRecording().delete(deleteLocation);

清除資源

如果您想要清除並移除通訊服務訂用帳戶,您可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。 深入了解如何清除資源

下一步

如需詳細資訊,請參閱下列文章: