Biblioteca cliente callAutomation de Azure Communication para .NET: versión 1.0.0

Artículo
06/21/2023

Este paquete contiene un SDK de C# para Azure Communication Call Automation.

Código | fuenteDocumentación del producto

Introducción

Instalar el paquete

Instale la biblioteca cliente CallAutomation de Azure Communication para .NET con NuGet:

dotnet add package Azure.Communication.CallAutomation

Prerrequisitos

Necesita una suscripción de Azure y un recurso de Communication Service para usar este paquete.

Para crear un servicio de comunicación, puede usar Azure Portal, el Azure PowerShell o la biblioteca cliente de administración de .NET.

Conceptos clave

CallAutomationClient proporciona la funcionalidad para responder a la llamada entrante o inicializar una llamada saliente.

Uso de las instrucciones

using Azure.Communication.CallAutomation;

Autenticar el cliente

El cliente de Automatización de llamadas se puede autenticar mediante la cadena de conexión adquirida desde un recurso de comunicación de Azure en Azure Portal.

var connectionString = "<connection_string>"; // Find your Communication Services resource in the Azure portal
CallAutomationClient callAutomationClient = new CallAutomationClient(connectionString);

También puede usar un token de Active Directory válido.

var endpoint = new Uri("https://my-resource.communication.azure.com");
TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CallAutomationClient(endpoint, tokenCredential);

Ejemplos

Realizar una llamada a un destinatario de número de teléfono

Para realizar una llamada saliente, llame a la CreateCall función o CreateCallAsync desde .CallAutomationClient

CallInvite callInvite = new CallInvite(
    new PhoneNumberIdentifier("<targets-phone-number>"),
    new PhoneNumberIdentifier("<caller-id-phonenumber>")
    );  // E.164 formatted recipient phone number

// create call with above invitation
createCallResult = await callAutomationClient.CreateCallAsync(
    callInvite,
    new Uri("<YOUR-CALLBACK-URL>")
    );

Console.WriteLine($"Call connection id: {createCallResult.CallConnectionProperties.CallConnectionId}");

Controlar eventos de devolución de llamada Mid-Connection

La aplicación recibirá eventos de devolución de llamada de conexión media a través del callbackEndpoint que proporcionó. Deberá escribir el controlador de controlador de eventos para recibir los eventos y dirigir el flujo de la aplicación en función de la lógica de negocios.

/// <summary>
/// Handle call back events.
/// </summary>>
[HttpPost]
[Route("/CallBackEvent")]
public IActionResult OnMidConnectionCallBackEvent([FromBody] CloudEvent[] events)
{
    try
    {
        if (events != null)
        {
            // Helper function to parse CloudEvent to a CallAutomation event.
            CallAutomationEventData callBackEvent = CallAutomationEventParser.Parse(events.FirstOrDefault());

            switch (callBackEvent)
            {
                case CallConnected ev:
                    # logic to handle a CallConnected event
                    break;
                case CallDisconnected ev:
                    # logic to handle a CallDisConnected event
                    break;
                case ParticipantsUpdated ev:
                    # cast the event into a ParticipantUpdated event and do something with it. Eg. iterate through the participants
                    ParticipantsUpdated updatedEvent = (ParticipantsUpdated)ev;
                    break;
                case AddParticipantSucceeded ev:
                    # logic to handle an AddParticipantSucceeded event
                    break;
                case AddParticipantFailed ev:
                    # logic to handle an AddParticipantFailed event
                    break;
                case CallTransferAccepted ev:
                    # logic to handle CallTransferAccepted event
                    break;
                case CallTransferFailed ev:
                    # logic to handle CallTransferFailed event
                    break;
                default:
                    break;
            }
        }
    }
    catch (Exception ex)
    {
        // handle exception
    }
    return Ok();
}

Controlar eventos de Mid-Connection con EventProcessor de CallAutomation

Para controlar fácilmente los eventos de conexión intermedia, el SDK de Call Automation proporciona una manera más sencilla de controlar estos eventos. Eche un vistazo a CallAutomationEventProcessor. esto garantizará que la correlación entre la llamada y los eventos sea más fácil.

[HttpPost]
[Route("/CallBackEvent")]
public IActionResult OnMidConnectionCallBackEvent([FromBody] CloudEvent[] events)
{
    try
    {
        // process incoming event for EventProcessor
        _callAutomationClient.GetEventProcessor().ProcessEvents(cloudEvents);
    }
    catch (Exception ex)
    {
        // handle exception
    }
    return Ok();
}

ProcessEvents es necesario para que EventProcessor funcione. Después de que EventProcessor consuma el evento, puede empezar a usar su característica.

Vea a continuación, por ejemplo: donde va a realizar una llamada con CreateCally espere a CallConnected que se produzca el evento de la llamada.

CallInvite callInvite = new CallInvite(
    new PhoneNumberIdentifier("<targets-phone-number>"),
    new PhoneNumberIdentifier("<caller-id-phonenumber>")
    );  // E.164 formatted recipient phone number

// create call with above invitation
createCallResult = await callAutomationClient.CreateCallAsync(
    callInvite,
    new Uri("<YOUR-CALLBACK-URL>")
    );

// giving 30 seconds timeout for call reciever to answer
CancellationTokenSource cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
CancellationToken token = cts.Token;

try
{
    // this will wait until CreateCall is completed or Timesout!
    CreateCallEventResult eventResult = await createCallResult.WaitForEventProcessorAsync(token);

    // Once this is recieved, you know the call is now connected.
    CallConnected returnedEvent = eventResult.SuccessResult;

    // ...Do more actions, such as Play or AddParticipant, since the call is established...
}
catch (OperationCanceledException ex)
{
    // Timeout exception happend!
    // Call likely was never answered.
}

Si no se pasó el token de cancelación con el tiempo de espera, el tiempo de espera predeterminado es de 4 minutos.

Solución de problemas

RequestFailedException Se produce como respuesta de servicio para las solicitudes incorrectas. La excepción contiene información sobre qué código de respuesta se devolvió desde el servicio.

Pasos siguientes

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Compartir a través de