你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure Communication CallAutomation 客户端库 - 版本 1.0.0

项目
06/21/2023

此包包含适用于 Azure 通信呼叫自动化的 C# SDK。

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure Communication CallAutomation 客户端库：

dotnet add package Azure.Communication.CallAutomation

必备知识

需要一个 Azure 订阅和一个通信服务资源才能使用此包。

若要创建新的通信服务，可以使用 Azure 门户、Azure PowerShell或 .NET 管理客户端库。

关键概念

CallAutomationClient 提供应答传入呼叫或初始化出站呼叫的功能。

使用语句

using Azure.Communication.CallAutomation;

验证客户端

可以使用从 Azure 门户中的 Azure 通信资源获取的连接字符串对调用自动化客户端进行身份验证。

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

或者，使用有效的 Active Directory 令牌。

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

示例

呼叫电话号码收件人

若要进行出站调用，请CreateCall从 CallAutomationClient调用或 CreateCallAsync 函数。

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

处理Mid-Connection回调事件

你的应用将通过你提供的 callbackEndpoint 接收中间连接回调事件。需要编写事件处理程序控制器来接收事件，并根据业务逻辑定向应用流。

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

使用 CallAutomation 的 EventProcessor 处理Mid-Connection事件

为了轻松处理中间连接事件，调用自动化的 SDK 提供了处理这些事件的更简单方法。查看 CallAutomationEventProcessor。这将确保更轻松地在调用和事件之间进行关联。

[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 是 EventProcessor 正常工作所必需的。 EventProcessor 使用事件后，可以开始使用其功能。

有关示例，请参阅以下示例：使用进行呼叫 CreateCall，并等待 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.
}

如果未通过超时传递取消令牌，则默认超时为 4 分钟。

疑难解答

RequestFailedException对于任何不成功的请求，将作为服务响应引发。异常包含有关从服务返回的响应代码的信息。

后续步骤

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

通过