Biblioteca de clientes CallAutomation de Comunicação do Azure para .NET – versão 1.0.0

Artigo
06/21/2023

Esse pacote contém um SDK do C# para a Automação de Chamadas de Comunicação do Azure.

Introdução

Instalar o pacote

Instale a biblioteca de clientes CallAutomation de Comunicação do Azure para .NET com o NuGet:

dotnet add package Azure.Communication.CallAutomation

Pré-requisitos

Você precisa de uma assinatura do Azure e um Recurso do Serviço de Comunicação para usar esse pacote.

Para criar um novo Serviço de Comunicação, você pode usar o Portal do Azure, o Azure PowerShell ou a biblioteca de clientes de gerenciamento do .NET.

Principais conceitos

CallAutomationClient fornece a funcionalidade para atender à chamada de entrada ou inicializar uma chamada de saída.

Como usar instruções

using Azure.Communication.CallAutomation;

Autenticar o cliente

O cliente de Automação de Chamadas pode ser autenticado usando a cadeia de conexão adquirida de um Recurso de Comunicação do Azure no Portal do Azure.

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

Ou, como alternativa, usar um token válido do Active Directory.

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

Exemplos

Fazer uma chamada para um destinatário de número de telefone

Para fazer uma chamada de saída, chame a CreateCall função ou CreateCallAsync do 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}");

Manipular eventos de retorno de chamada Mid-Connection

Seu aplicativo receberá eventos de retorno de chamada de conexão intermediária por meio do callbackEndpoint que você forneceu. Você precisará gravar o controlador do manipulador de eventos para receber os eventos e direcionar o fluxo do aplicativo com base na lógica de negócios.

/// <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();
}

Manipular eventos Mid-Connection com o EventProcessor da CallAutomation

Para lidar facilmente com eventos de conexão intermediária, o SDK da Automação de Chamadas fornece uma maneira mais fácil de lidar com esses eventos. Observe CallAutomationEventProcessor. isso garantirá a corelação entre chamadas e eventos com mais facilidade.

[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 é necessário para que o EventProcessor funcione. Depois que o evento estiver sendo consumido pelo EventProcessor, você poderá começar a usar seu recurso.

Veja abaixo, por exemplo: onde você está fazendo uma chamada com CreateCalle aguarde o CallConnected evento da chamada.

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.
}

Se o token de cancelamento não tiver sido passado com o tempo limite, o tempo limite padrão será de 4 minutos.

Solução de problemas

Um RequestFailedException é gerado como uma resposta de serviço para solicitações malsucedidas. A exceção contém informações sobre qual código de resposta foi retornado do serviço.

Próximas etapas

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Compartilhar via