呼び出し自動化のイベント プロセッサでのイベント処理の概要

呼び出し自動化を使用して呼び出しが確立されると、進行中の呼び出しの状態の更新は、Webhook Callback を介して別のイベントとして送信されます。 これらのイベントには、呼び出しの最新の状態や、送信された要求の結果などの重要な情報があります。

呼び出し自動化の EventProcessor は、アプリケーションのこれらの Webhook Callback イベントを簡単に処理します。 これは、各イベントをそれぞれの呼び出しに関連付け、アプリケーションを簡単にビルドするのに役立ちます。

メリット

EventProcessor 機能を使用することで、開発者は呼び出し自動化イベントを処理できる堅牢なアプリケーションを簡単にビルドできます。

• それぞれの呼び出しへのイベントの関連付け
• 線形のコードを簡単に記述可能
• 呼び出し中に発生する可能性のあるイベントの処理 (CallDisconnected や ParticipantsUpdated など)
• 要求の応答よりも早く到着するイベントがまれに発生する場合の処理
• イベント待機時間のカスタム タイムアウトを設定する

呼び出し自動化の EventProcessor にイベントを渡す

呼び出し自動化の EventProcessor では、まずサービスから送信されたイベントを使用する必要があります。 イベントがコールバック エンドポイントに到着したら、そのイベントを EventProcessor に渡します。

重要

Webhook コールバック イベントのエンドポイントを確立しましたか? EventProcessor は、Webhook コールバックを通じてコールバック イベントを使用する必要があります。 Webhook エンドポイントの確立については、クイックスタートを参照してください。

using Azure.Communication.CallAutomation;

[HttpPost]
public IActionResult CallbackEvent([FromBody] CloudEvent[] cloudEvents)
{
    // Use your call automation client that established the call
    CallAutomationEventProcessor eventProcessor = callAutomationClient.GetEventProcessor();

    // Let event be processed in EventProcessor
    eventProcessor.ProcessEvents(cloudEvents);
    return Ok();
}

これで、EventProcessor を使用する準備が整いました。

[接続された呼び出し] イベントを待機するための [呼び出しの作成] 要求の応答の使用

最初のシナリオは、送信呼び出しを作成し、EventProcessor を使用した呼び出しが確立されるまで待機することです。

// Creating an outbound call here
CreateCallResult createCallResult = await callAutomationClient.CreateCallAsync(callInvite, callbackUri);
CallConnection callConnection = createCallResult.CallConnection;

// Wait for 40 seconds before throwing timeout error.
var tokenSource = new CancellationTokenSource(TimeSpan.FromSeconds(40));

// We can wait for EventProcessor that related to outbound call here. In this case, we are waiting for CreateCallEventResult, upto 40 seconds.
CreateCallEventResult eventResult = await createCallResult.WaitForEventProcessorAsync(tokenSource);

// Once EventResult comes back, we can get SuccessResult of CreateCall - which is, CallConnected event.
CallConnected returnedEvent = eventResult.SuccessResult;

EventProcessor を使用することで、呼び出しが確立するまで CallConnected イベントを簡単に待機できます。 呼び出しが確立されなかった場合 (呼び出し先が電話に出なかった場合)、タイムアウト例外をスローします。 呼び出しの作成が別の原因で失敗した場合は、さらなるトラブルシューティングを行うためのエラー コードと共に CallDisconnected および CreateCallFailed イベントを受け取ることになります (Call Automation のエラー コードの詳細については、こちらのページを参照してください)。

Note

EventProcessor で待機するときに特定のタイムアウトが付与されなかった場合、既定のタイムアウトが発生するまで待機します。 既定のタイムアウト時間は 4 分です。

[再生] イベントを待機するための [再生] 要求の応答の使用

呼び出しが確立されたので、通話中にオーディオを再生し、メディアが再生されるまで待機してみましょう。

// play my prompt to everyone
FileSource fileSource = new FileSource(playPrompt);
PlayResult playResult = await callConnection.GetCallMedia().PlayToAllAsync(fileSource);

// wait for play to complete
PlayEventResult playEventResult = await playResult.WaitForEventProcessorAsync();

// check if the play was completed successfully
if (playEventResult.IsSuccess)
{
    // success play!
    PlayCompleted playCompleted = playEventResult.SuccessResult;
}
else
{
    // failed to play the audio.
    PlayFailed playFailed = playEventResultResult.FailureResult;
}

警告

EventProcessor では OperationContext を利用して、イベントとそれに関連する要求を追跡します。 要求中に OperationContext が設定されなかった場合、EventProcessor は、要求に対する将来のイベントを追跡するために、生成された GUID を設定します。 要求中に独自の OperationContext を設定している場合、EventProcessor は引き続き動作しますが、EventProcessor が要求 1 のイベントと要求 2 のイベントを区別できるように、要求ごとに異なる OperationContext を設定することをお勧めします。

進行中の EventProcessor を使用したイベントの処理

呼び出し中にいつでも発生する可能性のあるイベントがあります (CallDisconnected や ParticipantsUpdated など、他の呼び出し元が呼び出しから退出した場合)。 EventProcessor には、進行中のイベント ハンドラーでこれらのイベントを簡単に処理する方法が用意されています。

// Use your call automation client that established the call
CallAutomationEventProcessor eventProcessor = callAutomationClient.GetEventProcessor();

// attatch ongoing EventProcessor for this particular call,
// then prints out # of participants in the call
eventProcessor.AttachOngoingEventProcessor<ParticipantsUpdated>(callConnectionId, recievedEvent => {
    logger.LogInformation($"Number of participants in this Call: [{callConnectionId}], Number Of Participants[{recievedEvent.Participants.Count}]");
});

この進行中の EventProcessor を使用すると、呼び出しに参加したり退出したりするたびに、呼び出し中の番号や参加者を表示できるようになります。

ヒント

どんなイベントの種類にも進行中のハンドラーをアタッチできます。 これにより、コールバック設計パターンを使用してアプリケーションをビルドする可能性が広がります。

高度な方法: 特定のイベントを待機するための述語の使用

要求から返される EventResult に依存することなく、指定された述語を持つ特定のイベントを待機する場合、述語を使用してこれを行うこともできます。 CallConnectionId とその種類が一致する CallDisconnected イベントを待機してみましょう。

// Use your call automation client that established the call
CallAutomationEventProcessor eventProcessor = callAutomationClient.GetEventProcessor();

// With given matching informations, wait for this specific event
CallDisconnected disconnectedEvent = (CallDisconnected)await eventProcessor.WaitForEvent(predicate
=>
    predicate.CallConnectionId == myConnectionId
    && predicate.GetType() == typeof(CallDisconnected)
);

高度な方法: 詳細な仕様

• EventProcessor で待機するための既定のタイムアウトは 4 分です。 その後、タイムアウト例外がスローされます。
• 要求を行ったのと同じ呼び出し自動化クライアントは、EventProcessor を使用してイベントを待機するために使用する必要があります。
• 呼び出しの CallDisconnect イベントを受信すると、その呼び出しのすべてのイベントがメモリから削除されます。
• まれに、要求の応答よりも早くイベントが到着する場合もあります。 このような場合、バックログに 5 秒間保存されます。
• 同じイベントに対して複数の EventProcessor を待機させることができる。 一致するイベントが到着すると、そのイベントを待機しているすべての EventProcessor が到着したイベントとともに返されます。

次のステップ

• Call Automation を使用して呼び出しを制御および操作する方法の詳細について説明します。