Guida introduttiva: Gestire una chiamata alla sala

Introduzione

Durante una chiamata in sala Servizi di comunicazione di Azure (ACS), è possibile gestire la chiamata usando gli SDK per chiamate o gli SDK di Automazione delle chiamate o entrambi. In una chiamata alla sala è possibile controllare le azioni in chiamata usando entrambi i ruoli assegnati ai partecipanti e alle proprietà configurate nella sala. Le funzionalità di controllo dei ruoli del partecipante consentite per partecipante, mentre le proprietà della sala si applicano alla chiamata di sala nel suo complesso.

Calling SDK

L'SDK per chiamate è una libreria di chiamate lato client che consente ai partecipanti di una chiamata in sala di eseguire diverse operazioni in chiamata, ad esempio la condivisione dello schermo, attivare/disattivare video, disattivare o disattivare l'audio e così via. Per l'elenco completo delle funzionalità, vedere Panoramica dell'SDK per chiamate.

È possibile controllare le funzionalità in base ai ruoli assegnati ai partecipanti nella chiamata. Ad esempio, solo il relatore può condividere lo schermo. Per i ruoli e le autorizzazioni dei partecipanti, vedere Concetti relativi alle sale.

Chiamare gli SDK di Automazione delle chiamate

Call Automation SDK è una libreria lato server che consente agli amministratori di gestire una chiamata in sala in corso in un ambiente centrale e controllato. A differenza di Calling SDK, le operazioni di Call Automation SDK sono indipendenti dai ruoli. Pertanto, un amministratore di chiamata può eseguire diverse operazioni in chiamata per conto dei partecipanti alle chiamate in sala.

Gli elenchi seguenti descrivono le azioni comuni in chiamata disponibili in una chiamata alla sala.

Connettersi a una chiamata alla sala

L'automazione delle chiamate deve connettersi a una chiamata di sala esistente prima di eseguire qualsiasi operazione in chiamata. Gli CallConnected eventi o ConnectFailed vengono generati usando meccanismi di callback per indicare se un'operazione di connessione ha avuto esito positivo o negativo rispettivamente.

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)

Una volta stabilita la connessione a una chiamata alla sala, un CallConnect evento viene informato tramite l'URI di callback. È possibile usare callConnectionId per recuperare una connessione di chiamata nella chiamata alla sala in base alle esigenze. I frammenti di codice di esempio seguenti usano per callConnectionId illustrare questa funzione.

Aggiungere un partecipante PSTN

Usando Call Automation è possibile effettuare la chiamata a un numero PSTN e aggiungere il partecipante a una chiamata in sala. È tuttavia necessario configurare una stanza per abilitare l'opzione di uscita PSTN (EnabledPSTNDialout impostata su true) e la risorsa Servizi di comunicazione di Azure deve avere un numero di telefono valido di cui è stato effettuato il provisioning.

Per altre informazioni, vedere Guida introduttiva alle sale.

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>"
)

Rimuovere un partecipante 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>")

Inviare DTMF

Inviare un elenco di toni DTMF a un partecipante esterno.

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")

Registrazione delle chiamate

Servizi di comunicazione di Azure rooms supportano funzionalità di registrazione, tra cui start, stoppause, resume, e così via, fornite da Automazione chiamate. Vedere i frammenti di codice seguenti per avviare/arrestare/sospendere/riprendere una registrazione in una chiamata alla sala. Per un elenco completo delle azioni, vedere Registrazione di Automazione chiamate.

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)

Terminare una chiamata

È possibile usare l'azione Di blocco di Call Automation SDK per terminare una chiamata. Al termine dell'azione Di sospensione, l'SDK pubblica un CallDisconnected evento.

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)

Altre azioni

Le azioni in chiamata seguenti sono supportate anche in una chiamata alla sala.

1. Aggiungi partecipante (identificatore ACS)
2. Rimuovi partecipante (identificatore ACS)
3. Annulla aggiunta partecipante (identificatore ACS e numero PSTN)
4. Hang up call
5. Ottenere il partecipante (identificatore ACS e numero PSTN)
6. Ottenere più partecipanti (identificatore ACS e numero PSTN)
7. Ottenere informazioni più recenti su una chiamata
8. Riprodurre sia file audio che testo
9. Riprodurre tutti i file audio e il testo
10. Riconoscere sia DTMF che riconoscimento vocale
11. Riconoscere DTMF continuo

Per altre informazioni, vedere Chiamare azioni e azioni multimediali.

Passaggi successivi

In questa sezione si è appreso come:

• Partecipare a una chiamata di sala dall'applicazione
• Aggiungere azioni di chiamata in una chiamata alla sala tramite SDK per chiamate
• Aggiungere azioni di chiamata in una chiamata alla sala usando gli SDK di Automazione delle chiamate

Può essere utile vedere anche gli articoli seguenti:

• Informazioni sul concetto di Rooms
• Informazioni sulle funzionalità degli SDK per chiamate
• Informazioni sui concetti di Automazione delle chiamate