Azure Communication CallAutomation-Clientbibliothek für .NET– Version 1.0.0

Artikel
06/21/2023

Dieses Paket enthält ein C#-SDK für die Azure Communication Call Automation.

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Communication CallAutomation-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Communication.CallAutomation

Voraussetzungen

Sie benötigen ein Azure-Abonnement und eine Communication Service-Ressource , um dieses Paket verwenden zu können.

Um einen neuen Communication Service zu erstellen, können Sie das Azure-Portal, die Azure PowerShell oder die .NET-Verwaltungsclientbibliothek verwenden.

Wichtige Begriffe

CallAutomationClient stellt die Funktionalität bereit, um eingehende Anrufe zu beantworten oder einen ausgehenden Anruf zu initialisieren.

Verwenden von Anweisungen

using Azure.Communication.CallAutomation;

Authentifizieren des Clients

Der Anrufautomatisierungsclient kann mithilfe der Verbindungszeichenfolge authentifiziert werden, die von einer Azure-Kommunikationsressource im Azure-Portal abgerufen wurde.

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

Alternativ können Sie auch ein gültiges Active Directory-Token verwenden.

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

Beispiele

Tätigen eines Anrufs an einen Telefonnummernempfänger

Um einen ausgehenden Aufruf zu tätigen, rufen Sie die - oder CreateCallAsync -CreateCallFunktion aus der CallAutomationClientauf.

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

Behandeln von Mid-Connection Rückrufereignissen

Ihre App empfängt Rückrufereignisse während der Verbindung über den von Ihnen angegebenen callbackEndpoint. Sie müssen einen Ereignishandlercontroller schreiben, um die Ereignisse zu empfangen und den App-Fluss basierend auf Ihrer Geschäftslogik zu leiten.

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

Behandeln von Mid-Connection Ereignissen mit dem EventProcessor von CallAutomation

Das SDK von Call Automation bietet eine einfachere Möglichkeit, diese Ereignisse zu verarbeiten, um Ereignisse in der Mitte der Verbindung problemlos zu verarbeiten. Sehen Sie sich CallAutomationEventProcessor an. Dadurch wird eine einfachere Korelation zwischen Aufrufen und Ereignissen sichergestellt.

[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 ist erforderlich, damit EventProcessor funktioniert. Nachdem das Ereignis von EventProcessor genutzt wurde, können Sie mit der Verwendung des Features beginnen.

Siehe unten zum Beispiel: Wo Sie einen Anruf mit CreateCalltätigen und auf das Ereignis des Anrufs warten CallConnected .

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

Wenn das Abbruchtoken nicht mit timeout übergeben wurde, beträgt das Standardtimeout 4 Minuten.

Problembehandlung

Ein RequestFailedException wird als Dienstantwort für nicht erfolgreiche Anforderungen ausgelöst. Die Ausnahme enthält Informationen darüber, welcher Antwortcode vom Dienst zurückgegeben wurde.

Nächste Schritte

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Freigeben über