クイック スタート: ルーム通話の管理

はじめに

Azure Communication Services (ACS) でのルーム通話中に、Calling SDK または Call Automation SDK (またはその両方) を使用して通話を管理できます。 ルーム通話では、参加者に割り当てられたロールおよび、ルームで構成されたプロパティの両方を使用して、通話アクションを制御できます。 参加者のロールは参加者ごとに許可される機能を制御します。一方、ルームのプロパティはルーム通話全体に適用されます。

SDK の呼び出し

Calling SDK はクライアント側呼び出しライブラリであり、ルーム通話の参加者が画面共有、ビデオのオン/オフ、ミュート/ミュート解除などの複数の通話操作を実行できます。 機能の完全な一覧については、「Calling SDK の概要」を参照してください。

通話の参加者に割り当てられたロールに基づいて機能を制御します。 たとえば、発表者のみが画面共有を実行できます。 参加者の役割とアクセス許可については、「ルーム の概念」を参照してください。

Call Automation SDK

Call Automation SDK はサーバー側ライブラリであり、管理者が一元的な制御された環境で、進行中のルーム通話を管理できます。 Calling SDK とは異なり、Call Automation SDK の操作はロールに依存しません。 したがって、通話管理者は、会議室の通話参加者に代わって複数のインコール操作を実行できます。

次のリストは、ルーム通話で使用できる一般的な通話アクションを示しています。

ルーム通話に接続する

Call Automation は、通話操作を実行する前に、既存のルーム通話に接続する必要があります。 CallConnected イベントや ConnectFailed イベントはそれぞれ、接続操作が成功したか失敗したかを示すコールバック メカニズムを使用して発生します。

csharp

Uri callbackUri = new Uri("https://<myendpoint>/Events"); //the callback endpoint where you want to receive subsequent events
CallLocator roomCallLocator = new RoomCallLocator("<RoomId>");
ConnectCallResult response = await client.ConnectAsync(roomCallLocator, callbackUri);

Java

String callbackUri = "https://<myendpoint>/Events"; //the callback endpoint where you want to receive subsequent events
CallLocator roomCallLocator =  new RoomCallLocator("<RoomId>");
ConnectCallResult response = client.connectCall(roomCallLocator, callbackUri).block();

JavaScript

const roomCallLocator = { kind: "roomCallLocator", id: "<RoomId>" };
const callbackUri = "https://<myendpoint>/Events"; // the callback endpoint where you want to receive subsequent events 
const response = await client.connectCall(roomCallLocator, callbackUri);

Python

callback_uri = "https://<myendpoint>/Events"  # the callback endpoint where you want to receive subsequent events
room_call_locator = RoomCallLocator("<room_id>")
call_connection_properties = client.connect_call(call_locator=room_call_locator, callback_url=callback_uri)

ルーム通話に正常に接続されると、Callback URI を介して CallConnect イベントが通知されます。 必要に応じて callConnectionId を使用すると、ルーム通話の通話接続を取得できます。 次のサンプル コード スニペットでは、callConnectionId を使用してこの関数を実証しています。

PSTN 参加者を追加する

Call Automation を使用すると、PSTN 番号にダイヤルアウトし、ルーム通話に参加者を追加できます。 ただし、ルームをセットアップして PSTN ダイヤルアウト オプション (EnabledPSTNDialout は trueに設定) を有効にする必要があり、Azure Communication Services リソースに有効な電話番号がプロビジョニングされている必要があります。

詳細については、「ルームのクイックスタート」を参照してください。

csharp

var callerIdNumber = new PhoneNumberIdentifier("+16044561234"); // This is the ACS-provisioned phone number for the caller  
var callThisPerson = new CallInvite(new PhoneNumberIdentifier("+16041234567"), callerIdNumber); // The target phone number to dial out to
CreateCallResult response = await client.GetCallConnection(callConnectionId).AddParticipantAsync(callThisPerson);

Java

PhoneNumberIdentifier callerIdNumber = new PhoneNumberIdentifier("+16044561234"); // This is the ACS-provisioned phone number for the caller
CallInvite callInvite = new CallInvite(new PhoneNumberIdentifier("+16041234567"), callerIdNumber); // The phone number participant to dial out to
AddParticipantOptions addParticipantOptions = new AddParticipantOptions(callInvite);
Response<AddParticipantResult> addParticipantResultResponse = client.getCallConnectionAsync(callConnectionId)
    .addParticipantWithResponse(addParticipantOptions).block();

JavaScript

const callInvite = {
    targetParticipant: { phoneNumber: "+18008008800" }, // The phone number participant to dial out to
    sourceCallIdNumber: { phoneNumber: "+18888888888" } // This is the ACS-provisioned phone number for the caller
};
const response = await client.getCallConnection(callConnectionId).addParticipant(callInvite);

Python

caller_id_number = PhoneNumberIdentifier(
    "+18888888888"
) # TThis is the ACS-provisioned phone number for the caller
target = PhoneNumberIdentifier("+18008008800"), # The phone number participant to dial out to

call_connection_client = call_automation_client.get_call_connection(
    "call_connection_id"
)
result = call_connection_client.add_participant(
    target,
    operation_context="Your context",
    operationCallbackUrl="<url_endpoint>"
)

PSTN 参加者を削除する

csharp

var removeThisUser = new PhoneNumberIdentifier("+16044561234");

// Remove a participant from the call with optional parameters
var removeParticipantOptions = new RemoveParticipantOptions(removeThisUser)
{
    OperationContext = "operationContext",
    OperationCallbackUri = new Uri("uri_endpoint"); // Sending event to a non-default endpoint
}

RemoveParticipantsResult result = await client.GetCallConnection(callConnectionId).RemoveParticipantAsync(removeParticipantOptions);

Java

CommunicationIdentifier removeThisUser = new PhoneNumberIdentifier("+16044561234");
RemoveParticipantOptions removeParticipantOptions = new RemoveParticipantOptions(removeThisUser)
                .setOperationContext("<operation_context>")
                .setOperationCallbackUrl("<url_endpoint>");
Response<RemoveParticipantResult> removeParticipantResultResponse = client.getCallConnectionAsync(callConnectionId)
    .removeParticipantWithResponse(removeParticipantOptions);

JavaScript

const removeThisUser = { phoneNumber: "+16044561234" };
const removeParticipantResult = await client.getCallConnection(callConnectionId).removeParticipant(removeThisUser);

Python

remove_this_user = PhoneNumberIdentifier("+16044561234")
call_connection_client = call_automation_client.get_call_connection(
    "call_connection_id"
)
result = call_connection_client.remove_participant(remove_this_user, operation_context="Your context", operationCallbackUrl="<url_endpoint>")

DTMF 送信

DTMF トーンの一覧を外部参加者に送信します。

csharp

var tones = new DtmfTone[] { DtmfTone.One, DtmfTone.Two, DtmfTone.Three, DtmfTone.Pound }; 
var sendDtmfTonesOptions = new SendDtmfTonesOptions(tones, new PhoneNumberIdentifier(calleePhonenumber))
{ 
	OperationContext = "dtmfs-to-ivr" 
}; 

var sendDtmfAsyncResult = await callAutomationClient.GetCallConnection(callConnectionId).GetCallMedia().SendDtmfTonesAsync(sendDtmfTonesOptions);

Java

List<DtmfTone> tones = Arrays.asList(DtmfTone.ONE, DtmfTone.TWO, DtmfTone.THREE, DtmfTone.POUND); 
SendDtmfTonesOptions options = new SendDtmfTonesOptions(tones, new PhoneNumberIdentifier(c2Target)); 
options.setOperationContext("dtmfs-to-ivr"); 
client.getCallConnectionAsync(callConnectionId)
	.getCallMediaAsync() 
	.sendDtmfTonesWithResponse(options) 
	.block(); 

JavaScript

const tones = [DtmfTone.One, DtmfTone.Two, DtmfTone.Three];
const sendDtmfTonesOptions: SendDtmfTonesOptions = {
	operationContext: "dtmfs-to-ivr"
};
const result: SendDtmfTonesResult = await client.getCallConnection(callConnectionId)
	.getCallMedia()
	.sendDtmfTones(tones, {
		phoneNumber: c2Target
	}, sendDtmfTonesOptions);
console.log("sendDtmfTones, result=%s", result);

Python

tones = [DtmfTone.ONE, DtmfTone.TWO, DtmfTone.THREE]
call_connection_client = call_automation_client.get_call_connection(
    "call_connection_id"
)

result = call_connection_client.send_dtmf_tones(
	tones = tones,
	target_participant = PhoneNumberIdentifier(c2_target),
	operation_context = "dtmfs-to-ivr")

通話レコーディング

Azure Communication Services ルームでは、Call Automation によって提供される start、stop、pause、resume などの記録機能がサポートされます。 ルーム通話の記録を開始、停止、一時停止、再開するには、次のコード スニペットを参照してください。 アクションの完全な一覧については、「Call Automation での記録」を参照してください。

csharp

// Start recording
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);

// Pause recording using recordingId received in response of start recording.
var pauseRecording = await callAutomationClient.GetCallRecording ().PauseAsync(recordingId);

// Resume recording using recordingId received in response of start recording.
var resumeRecording = await callAutomationClient.GetCallRecording().ResumeAsync(recordingId);

// Stop recording using recordingId received in response of start recording.
var stopRecording = await callAutomationClient.GetCallRecording().StopAsync(recordingId);

Java

// Start recording
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);

// Pause recording using recordingId received in response of start recording
Response<Void> response = callAutomationClient.getCallRecording()
              .pauseWithResponse(recordingId, null);

// Resume recording using recordingId received in response of start recording
Response<Void> response = callAutomationClient.getCallRecording()
               .resumeWithResponse(recordingId, null);

// Stop recording using recordingId received in response of start recording
Response<Void> response = callAutomationClient.getCallRecording()
               .stopWithResponse(recordingId, null);

JavaScript

// Start recording
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);

// Pause recording using recordingId received in response of start recording
var pauseRecording = await callAutomationClient.getCallRecording().pause(recordingId);

// Resume recording using recordingId received in response of start recording.
var resumeRecording = await callAutomationClient.getCallRecording().resume(recordingId);

// Stop recording using recordingId received in response of start recording
var stopRecording = await callAutomationClient.getCallRecording().stop(recordingId);

Python

# Start recording
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>")

# Pause recording using recording_id received in response of start recording
pause_recording = call_automation_client.pause_recording(recording_id = recording_id)

# Resume recording using recording_id received in response of start recording
resume_recording = call_automation_client.resume_recording(recording_id = recording_id)

# Stop recording using recording_id received in response of start recording
stop_recording = call_automation_client.stop_recording(recording_id = recording_id)

通話を終了する

Call Automation SDK の Hang Up アクションを使用して、呼び出しを終了できます。 Hang Up アクションが完了すると、SDK が CallDisconnected イベントを発行します。

csharp

_ = await client.GetCallConnection(callConnectionId).HangUpAsync(forEveryone: true); 

Java

Response<Void> response = client.getCallConnectionAsync(callConnectionId).hangUpWithResponse(true).block();

JavaScript

await callConnection.hangUp(true);

Python

call_connection_client = call_automation_client.get_call_connection(
    "call_connection_id"
)

call_connection_client.hang_up(is_for_everyone=True)

その他のアクション

ルーム通話では、次の通話アクションもサポートされます。

1. 参加者の追加 (ACS 識別子)
2. 参加者の削除 (ACS 識別子)
3. 参加者の追加を取り消す (ACS 識別子と PSTN 番号)
4. 通話を切る
5. 参加者の取得 (ACS 識別子と PSTN 番号)
6. 複数の参加者を取得する (ACS 識別子と PSTN 番号)
7. 通話に関する最新情報を取得する
8. オーディオ ファイルおよびテキストの再生
9. すべてのオーディオ ファイルおよびテキストの再生
10. DTMF と音声の両方を認識する
11. 継続的 DTMF を認識する

詳細については、「アクションの呼び出し」および「メディア アクション」を参照してください。

次のステップ

このセクションでは、次の方法について学習しました。

• アプリケーションからルーム通話に参加する
• Calling SDK を使用してルーム通話に通話アクションを追加する
• Call Automation SDK を使用して室内通話に通話アクションを追加する

次のことも実行できます。

• ルームの概念について
• Calling SDK の機能について
• Call Automation の概念について