.NET 用 Azure Communication CallAutomation クライアント ライブラリ - バージョン 1.0.0

  • [アーティクル]

このパッケージには、Azure Communication Call Automation 用の C# SDK が含まれています。

ソースコード | 製品ドキュメント

作業の開始

パッケージをインストールする

NuGet を使用して .NET 用の Azure Communication CallAutomation クライアント ライブラリをインストールします。

dotnet add package Azure.Communication.CallAutomation

前提条件

このパッケージを使用するには、 Azure サブスクリプション と Communication Service リソース が必要です。

新しい Communication Service を作成するには、Azure Portal、Azure PowerShell、または .NET 管理クライアント ライブラリを使用できます。

主要な概念

CallAutomationClient は、着信に応答したり、発信呼び出しを初期化したりする機能を提供します。

ステートメントの使用

using Azure.Communication.CallAutomation;

クライアントを認証する

Call Automation クライアントは、 Azure Portal の Azure Communication Resource から取得した接続文字列を使用して認証できます。

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

例

電話番号の受信者に電話をかける

送信呼び出しを行うには、 から または CreateCallAsync 関数を呼び出CreateCallします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}");

コールバック イベント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) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。