ユーザーの機能を観察する

私には、ビデオをオンにするアクセス許可がありますか? マイクをオンにするアクセス許可はありますか? 画面を共有するアクセス許可がありますか? これらのアクセス許可は、機能 API から学ぶことができるいくつかの参加者機能の例です。 機能を学ぶことは、ローカル ユーザーが権限を持っているアクションに関連したボタンのみを表示するユーザー インターフェイスを作成するのに役立ちます。

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
• デプロイ済みの Communication Services リソース。 Communication Services リソースを作成します。
• 通話クライアントを有効にするためのユーザー アクセス トークン。 詳細については、アクセス トークンの作成と管理に関する記事を参照してください。
• 省略可能: クイックスタートを完了して、アプリケーションに音声通話を追加します

SDK のインストール

npm install コマンドを使用して、JavaScript 用の Azure Communication Services の Common SDK と Calling SDK をインストールします。

npm install @azure/communication-common --save
npm install @azure/communication-calling --save

必要なオブジェクトを初期化する

CallClient インスタンスは、ほとんどの通話操作に必要です。 新しい CallClient インスタンスを作成する際に、Logger インスタンスなどのカスタム オプションを使用してこれを構成できます。

CallClient インスタンスでは、createCallAgent を呼び出すことで CallAgent インスタンスを作成できます。 このメソッドでは、非同期的に CallAgent インスタンス オブジェクトが返されます。

createCallAgent メソッドでは、CommunicationTokenCredential が引数として使用されます。 これは、ユーザー アクセス トークンを受け取ります。

CallClient インスタンスで getDeviceManager メソッドを使用して、deviceManager にアクセスできます。

const { CallClient } = require('@azure/communication-calling');
const { AzureCommunicationTokenCredential} = require('@azure/communication-common');
const { AzureLogger, setLogLevel } = require("@azure/logger");

// Set the logger's log level
setLogLevel('verbose');

// Redirect log output to console, file, buffer, REST API, or whatever location you want
AzureLogger.log = (...args) => {
    console.log(...args); // Redirect log output to console
};

const userToken = '<USER_TOKEN>';
callClient = new CallClient(options);
const tokenCredential = new AzureCommunicationTokenCredential(userToken);
const callAgent = await callClient.createCallAgent(tokenCredential, {displayName: 'optional Azure Communication Services user name'});
const deviceManager = await callClient.getDeviceManager()

Microsoft インフラストラクチャへの SDK 接続を最適に管理する方法

Call Agent インスタンスは、(呼び出しを結合または開始するために) 呼び出しを管理するのに役立ちます。 呼び出しの SDK を機能させるには、Microsoft インフラストラクチャに接続して着信呼び出しの通知を取得し、他の呼び出しの詳細を調整する必要があります。 Call Agent には、次の 2 つの状態があります。

接続済み - Connected の Call Agent connectionStatue 値は、クライアント SDK が接続されており、Microsoft インフラストラクチャから通知を受信できることを意味します。

切断済み - Disconnected の Call Agent connectionStatue 値は、SDK の正常な接続を妨げる問題があることを示します。 Call Agent を再作成する必要があります。

• invalidToken: トークンが有効期限切れであるか、無効な場合、Call Agent インスタンスがこのエラーで切断されます。
• connectionIssue: クライアントの Microsoft インフラストラクチャへの接続で問題が発生した場合、何度も再試行した後に、Call Agent が connectionIssue エラーを提示します。

connectionState プロパティの現在の値を調べて、ローカル Call Agent が Microsoft インフラストラクチャに接続されているかどうかを確認できます。 アクティブな呼び出し中に、connectionStateChanged イベントをリッスンして、Call Agent の状態が接続から切断に変化するかどうかを判断できます。

const connectionState = callAgentInstance.connectionState;
console.log(connectionState); // it may return either of 'Connected' | 'Disconnected'

const connectionStateCallback = (args) => {
    console.log(args); // it will return an object with oldState and newState, each of having a value of either of 'Connected' | 'Disconnected'
    // it will also return reason, either of 'invalidToken' | 'connectionIssue'
}
callAgentInstance.on('connectionStateChanged', connectionStateCallback);

Capabilities 機能は、コアとなる Call API の拡張機能の 1 つで、現在の通話におけるローカル参加者の機能を取得できるものです。

この機能を使用すると、イベント リスナーに登録し、機能の変更をリッスンできます。

Capabilities 機能に登録する:

const capabilitiesFeature = this.call.feature(Features.Capabilities);

ローカル参加者の機能を取得する: Capabilities オブジェクトにはローカル参加者機能があり、種類が ParticipantCapabilities です。 Capabilities のプロパティとして以下があります。

• isPresent は機能が存在するかどうかを示します。
• reason は機能の解決理由を示します。

const capabilities =  capabilitiesFeature.capabilities;

capabilitiesChanged イベントにサブスクライブします:

capabilitiesFeature.on('capabilitiesChanged', (capabilitiesChangeInfo) => {
    for (const [key, value] of Object.entries(capabilitiesChangeInfo.newValue)) {
        if(key === 'turnVideoOn' && value.reason != 'FeatureNotSupported') {
             (value.isPresent) ? this.setState({ canOnVideo: true }) : this.setState({ canOnVideo: false });
             continue;
        }
        if(key === 'unmuteMic' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canUnMuteMic: true }) : this.setState({ canUnMuteMic: false });
            continue;
        }
        if(key === 'shareScreen' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canShareScreen: true }) : this.setState({ canShareScreen: false });
            continue;
        }
        if(key === 'spotlightParticipant' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canSpotlight: true }) : this.setState({ canSpotlight: false });
            continue;
        }
        if(key === 'raiseHand' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canRaiseHands: true }) : this.setState({ canRaiseHands: false });
            continue;
        }
        if(key === 'muteOthers' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canMuteOthers: true }) : this.setState({ canMuteOthers: false });
            continue;
        }
        if(key === 'reaction' && value.reason != 'FeatureNotSupported') {
            (value.isPresent) ? this.setState({ canReact: true }) : this.setState({ canReact: false });
            continue;
        }
    }
});

機能を公開

• turnVideoOn: 動画をオンにする機能
• unmuteMic: マイクをオンにする機能
• shareScreen: 画面を共有する機能
• removeParticipant: 参加者を除去する機能
• hangUpForEveryOne: 誰に対しても電話を切る機能
• addCommunicationUser: 通信ユーザーを追加する機能
• addTeamsUser: チーム ユーザーを追加する機能
• addPhoneNumber: 電話番号を追加する機能
• manageLobby: ロビーを管理する機能 (ベータ版のみ)
• spotlightParticipant: 参加者にスポットライトを当てる機能 (ベータ版のみ)
• removeParticipantsSpotlight: 参加者スポットライトを除去する機能 (ベータ版のみ)
• startLiveCaptions: ライブ キャプションを開始する機能 (ベータ版のみ)
• stopLiveCaptions: ライブ キャプションを停止する機能 (ベータ版のみ)
• raiseHand: 手を上げる機能 (ベータ版のみ)
• muteOthers: 会議のリモート参加者をソフト ミュートする機能
• リアクション: 会議でリアクションする機能 (ベータ版のみ)
• viewAttendeeNames: 会議で出席者の名前を表示する機能

SDK のインストール

プロジェクト レベルの build.gradle ファイルを見つけて、buildscript と allprojects の下のリポジトリの一覧に mavenCentral() を追加します。

buildscript {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

allprojects {
    repositories {
    ...
        mavenCentral()
    ...
    }
}

次に、モジュール レベルの build.gradle ファイルで、次の行を dependencies セクションに追加します。

dependencies {
    ...
    implementation 'com.azure.android:azure-communication-calling:1.0.0'
    ...
}

必要なオブジェクトを初期化する

CallAgent インスタンスを作成するには、CallClient インスタンス上で createCallAgent メソッドを呼び出す必要があります。 この呼び出しは、CallAgent インスタンス オブジェクトを非同期に返します。

createCallAgent メソッドは、アクセス トークンをカプセル化する CommunicationUserCredential を引数として受け取ります。

DeviceManager にアクセスするには、まず callAgent インスタンスを作成する必要があります。 それから、CallClient.getDeviceManager メソッドを使用して DeviceManager を取得することができます。

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential).get();
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();

呼び出し元の表示名を設定するには、この代替メソッドを使用します。

String userToken = '<user token>';
CallClient callClient = new CallClient();
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(userToken);
android.content.Context appContext = this.getApplicationContext(); // From within an activity, for instance
CallAgentOptions callAgentOptions = new CallAgentOptions();
callAgentOptions.setDisplayName("Alice Bob");
DeviceManager deviceManager = callClient.getDeviceManager(appContext).get();
CallAgent callAgent = callClient.createCallAgent(appContext, tokenCredential, callAgentOptions).get();

Capabilities 機能は、コアとなる Call API の拡張機能の 1 つで、現在の通話におけるローカル参加者の機能を取得できるものです。

この機能を使用すると、イベント リスナーに登録し、機能の変更をリッスンできます。

Windows 用の Capabilities 通話機能を使用するための最初の手順は、Capabilities 機能 API オブジェクトを取得することです。

Capabilities 機能を取得する

private CapabilitiesCallFeature capabilitiesCallFeature;
capabilitiesCallFeature = call.feature(Features.CAPABILITIES);

ローカル参加者の機能を取得する

Capabilities オブジェクトには、ローカル参加者の機能が含まれており、型は ParticipantCapability です。 Capabilities のプロパティとして以下があります。

• isAllowed は、機能を使用できるかどうかを示します。
• reason は機能の解決理由を示します。

List<ParticipantCapability> capabilities = capabilitiesCallFeature.getCapabilities();

capabilitiesChanged イベントにサブスクライブする

capabilitiesCallFeature.addOnCapabilitiesChangedListener(this::OnCapabilitiesChanged);

private void OnCapabilitiesChanged(CapabilitiesChangedEvent args)
{
    String event = String.format("Capabilities Event: %s", args.getReason().toString());
    Log.i("CapabilitiesInfo", event);
    for (ParticipantCapability capability : args.getChangedCapabilities())
    {
        Log.i("CapabilitiesInfo", capability.getType().toString() + " is " capability.getReason().toString());
    }
}

機能を公開

• TurnVideoOn: ビデオをオンにする機能
• UnmuteMicrophone: マイクのミュート解除を行う機能
• ShareScreen: 画面を共有する機能
• RemoveParticipant: 参加者を削除する機能
• HangUpForEveryone: 全員に対して通話を切断する機能
• AddCommunicationUser: 通信ユーザーを追加する機能
• AddTeamsUser: Teams ユーザーを追加する機能
• AddPhoneNumber: 電話番号を追加する機能
• ManageLobby: ロビーを管理する機能
• SpotlightParticipant: 参加者にスポットライトを当てる機能
• RemoveParticipantSpotlight: 参加者のスポットライトを削除する機能
• BlurBackground: 背景をぼかす機能
• CustomBackground: カスタム背景を適用する機能
• StartLiveCaptions: ライブ キャプションを開始する機能
• RaiseHand: 挙手する機能
• MuteOthers: 会議のリモート参加者をソフト ミュートする機能

システムを設定する

次の手順のようにして、システムを設定します。

Visual Studio プロジェクトの作成

ユニバーサル Windows プラットフォーム アプリの場合は、Visual Studio 2022 で、新しい空のアプリ (ユニバーサル Windows) プロジェクトを作成します。 プロジェクト名を入力した後、10.0.17763.0 より後の Windows SDK を自由に選択できます。

WinUI 3 アプリの場合、Blank App, Packaged (WinUI 3 in Desktop) テンプレートで新しいプロジェクトを作成し、シングルページの WinUI 3 アプリを設定します。 Windows App SDK バージョン 1.3 以降が必要です。

NuGet パッケージ マネージャーを使用してパッケージと依存関係をインストールする

Calling SDK の API とライブラリは、NuGet パッケージにより一般公開されています。

Calling SDK NuGet パッケージを検索、ダウンロード、インストールするには:

1. [ツール]>[NuGet パッケージ マネージャー]>[ソリューションの NuGet パッケージの管理] を選んで、NuGet パッケージ マネージャーを開きます。
2. [参照] を選んでから、検索ボックスに「Azure.Communication.Calling.WindowsClient」と入力します。
3. [プレリリースを含める] チェックボックスがオンになっていることを確認します。
4. Azure.Communication.Calling.WindowsClient パッケージを選び、Azure.Communication.Calling.WindowsClient 1.4.0-beta.1 以降のバージョンを選びます。
5. 右側のペインで、Azure Communication Services プロジェクトに対応するチェックボックスをオンにします。
6. [インストール] を選択します。

Capabilities 機能は、コアとなる Call API の拡張機能の 1 つで、現在の通話におけるローカル参加者の機能を取得できるものです。

この機能を使用すると、イベント リスナーに登録し、機能の変更をリッスンできます。

Windows 用の Capabilities 通話機能を使用するための最初の手順は、Capabilities 機能 API オブジェクトを取得することです。

Capabilities 機能を取得する

private CapabilitiesCallFeature capabilitiesCallFeature;
capabilitiesCallFeature = call.Features.Capabilities;

ローカル参加者の機能を取得する

Capabilities オブジェクトには、ローカル参加者の機能が含まれており、型は ParticipantCapability です。 Capabilities のプロパティとして以下があります。

• isAllowed は、機能を使用できるかどうかを示します。
• reason は機能の解決理由を示します。

var capabilities = capabilitiesCallFeature.Capabilities;

capabilitiesChanged イベントにサブスクライブする

capabilitiesCallFeature.CapabilitiesChanged += Call__OnCapabilitiesChangedAsync;

private async void Call__OnCapabilitiesChangedAsync(object sender, CapabilitiesChangedEventArgs args)
{
    Trace.WriteLine(args.Reason.ToString());
    foreach (var capability in args.ChangedCapabilities)
    {
        //Prints out capability kind and resolution reason in console
        Trace.WriteLine(capability.Kind.ToString() + " is " + capability.Reason.ToString());
    }
}

機能を公開

• TurnVideoOn: ビデオをオンにする機能
• UnmuteMicrophone: マイクのミュート解除を行う機能
• ShareScreen: 画面を共有する機能
• RemoveParticipant: 参加者を削除する機能
• HangUpForEveryone: 全員に対して通話を切断する機能
• AddCommunicationUser: 通信ユーザーを追加する機能
• AddTeamsUser: Teams ユーザーを追加する機能
• AddPhoneNumber: 電話番号を追加する機能
• ManageLobby: ロビーを管理する機能
• SpotlightParticipant: 参加者にスポットライトを当てる機能
• RemoveParticipantSpotlight: 参加者のスポットライトを削除する機能
• BlurBackground: 背景をぼかす機能
• CustomBackground: カスタム背景を適用する機能
• StartLiveCaptions: ライブ キャプションを開始する機能
• RaiseHand: 挙手する機能
• MuteOthers: 会議のリモート参加者をソフト ミュートする機能

システムを設定する

次の手順のようにして、システムを設定します。

Xcode プロジェクトを作成する

Xcode で、新しい iOS プロジェクトを作成し、[単一ビュー アプリ] テンプレートを選択します。 この記事では SwiftUI フレームワークを使うので、[言語] を [Swift] に、[インターフェイス] を [SwiftUI] に設定する必要があります。

この記事では、テストは作成しません。 [Include Tests] チェック ボックスはオフにしてもかまいません。

CocoaPods を使用してパッケージと依存関係をインストールする

1. この例のように、アプリケーション用の Podfile を作成します。

   platform :ios, '13.0'
   use_frameworks!
   target 'AzureCommunicationCallingSample' do
       pod 'AzureCommunicationCalling', '~> 1.0.0'
   end
   

2. pod install を実行します。

3. Xcode を使用して .xcworkspace を開きます。

マイクへのアクセスを要求する

デバイスのマイクにアクセスするには、NSMicrophoneUsageDescription を使用してアプリの情報プロパティ一覧を更新する必要があります。 関連付けられる値には、システムがユーザーにアクセスを要求するために使うダイアログに含まれる文字列を設定します。

プロジェクト ツリーの [Info.plist] エントリを右クリックし、[Open As]>[Source Code] を選択します。 最上位の <dict> セクションに以下の行を追加してから、ファイルを保存します。

<key>NSMicrophoneUsageDescription</key>
<string>Need microphone access for VOIP calling.</string>

アプリのフレームワークを設定する

プロジェクトの ContentView.swift ファイルを開きます。 ファイルの先頭に import 宣言を追加して、AzureCommunicationCalling ライブラリをインポートします。 さらに、AVFoundation をインポートします。 これは、コードでのオーディオ アクセス許可の要求に必要です。

import AzureCommunicationCalling
import AVFoundation

CallAgent を初期化する

CallClient から CallAgent インスタンスを作成するには、初期化された後に CallAgent オブジェクトを非同期に返す callClient.createCallAgent メソッドを使用する必要があります。

通話クライアントを作成するには、CommunicationTokenCredential オブジェクトを渡します。

import AzureCommunication

let tokenString = "token_string"
var userCredential: CommunicationTokenCredential?
do {
    let options = CommunicationTokenRefreshOptions(initialToken: token, refreshProactively: true, tokenRefresher: self.fetchTokenSync)
    userCredential = try CommunicationTokenCredential(withOptions: options)
} catch {
    updates("Couldn't created Credential object", false)
    initializationDispatchGroup!.leave()
    return
}

// tokenProvider needs to be implemented by Contoso, which fetches a new token
public func fetchTokenSync(then onCompletion: TokenRefreshOnCompletion) {
    let newToken = self.tokenProvider!.fetchNewToken()
    onCompletion(newToken, nil)
}

作成した CommunicationTokenCredential オブジェクトを CallClient に渡し、表示名を設定します。

self.callClient = CallClient()
let callAgentOptions = CallAgentOptions()
options.displayName = " iOS Azure Communication Services User"

self.callClient!.createCallAgent(userCredential: userCredential!,
    options: callAgentOptions) { (callAgent, error) in
        if error == nil {
            print("Create agent succeeded")
            self.callAgent = callAgent
        } else {
            print("Create agent failed")
        }
})

Capabilities 機能は、コアとなる Call API の拡張機能の 1 つで、現在の通話におけるローカル参加者の機能を取得できるものです。

この機能を使用すると、イベント リスナーに登録し、機能の変更をリッスンできます。

Windows 用の Capabilities 通話機能を使用するための最初の手順は、Capabilities 機能 API オブジェクトを取得することです。

Capabilities 機能を取得する

let capabilitiesCallFeature =call.feature(Features.capabilities)

ローカル参加者の機能を取得する

Capabilities オブジェクトには、ローカル参加者の機能が含まれており、型は ParticipantCapability です。 Capabilities のプロパティとして以下があります。

• isAllowed は、機能を使用できるかどうかを示します。
• reason は機能の解決理由を示します。

var capabilities = capabilitiesCallFeature.capabilities

capabilitiesChanged イベントにサブスクライブする

capabilitiesCallFeature.delegate = CapabilitiesCallDelegate()

public class CapabilitiesCallDelegate : CapabilitiesCallFeatureDelegate
{
    public func capabilitiesCallFeature(_ capabilitiesCallFeature: CapabilitiesCallFeature, didChangeCapabilities args: CapabilitiesChangedEventArgs) {
        let changedReason = args.reason
        let changedCapabilities = args.changedCapabilities
    }
}

機能を公開

• TurnVideoOn: ビデオをオンにする機能
• UnmuteMicrophone: マイクのミュート解除を行う機能
• ShareScreen: 画面を共有する機能
• RemoveParticipant: 参加者を削除する機能
• HangUpForEveryone: 全員に対して通話を切断する機能
• AddCommunicationUser: 通信ユーザーを追加する機能
• AddTeamsUser: Teams ユーザーを追加する機能
• AddPhoneNumber: 電話番号を追加する機能
• ManageLobby: ロビーを管理する機能
• SpotlightParticipant: 参加者にスポットライトを当てる機能
• RemoveParticipantSpotlight: 参加者のスポットライトを削除する機能
• BlurBackground: 背景をぼかす機能
• CustomBackground: カスタム背景を適用する機能
• StartLiveCaptions: ライブ キャプションを開始する機能
• RaiseHand: 挙手する機能
• MuteOthers: 会議のリモート参加者をソフト ミュートする機能

サポートされている通話の種類

この機能は、現在は Azure Communication Services のルーム通話の種類とチーム会議通話の種類でのみサポートされています

理由

次の表は、アクションが使用できない理由に関する追加情報と、アクションを使用できるようにする方法のヒントを示しています。

理由	説明	解像度
対応	アクションは許可されています。
CapabilityNotApplicableForTheCallType	通話の種類によってアクションがブロックされます。	このアクションが必要な場合は、他の種類の通話を検討してください。 通話の種類は、1:1 通話、グループ通話、1:1 Teams 相互運用通話、1:1 Teams 相互運用グループ通話、ルーム、会議です。
ClientRestricted	ランタイム環境によりこのアクションがブロックされています	オペレーティング システム、ブラウザー、プラットフォーム、またはハードウェアを変更して、デバイスのアクションをブロック解除します。 サポートされている環境については、ドキュメントを参照してください。
UserPolicyRestricted	Microsoft 365 ユーザーのポリシーによってアクションがブロックされます。	ACS SDK を使用して、会議の開催者、通話の発信者、または Microsoft 365 ユーザーに割り当てられているポリシーを変更して、このアクションを有効にします。 ターゲット ユーザーは、アクションの種類によって異なります。 Teams の Teams ポリシーの詳細をご確認ください。 Teams 管理者はポリシーを変更できます。
RoleRestricted	割り当てられたロールによってアクションがブロックされます。	ユーザーを別のロールに昇格して、アクションを使用できるようにします。
FeatureNotSupported	この通話の種類では、機能はサポートされていません。	この通話の種類でこの機能をご利用になりたい場合は、Azure フィードバック チャネルでお知らせください。
MeetingRestricted	Teams 会議オプションにより、アクションがブロックされています。	Teams 会議の開催者または共同開催者は、このアクションを有効にするために会議オプションを変更する必要があります。
NotInitialized	この機能はまだ初期化されていません。	機能が初期化されるタイミングを知るために、 this.call.feature(Features.Capabilities) のイベント capabilitiesChanged にサブスクライブします。
NotCapable	ユーザーの種類によってアクションがブロックされます。	アクションは、特定の種類の ID にのみ許可されます。 Microsoft 365 ID を使用して、このアクションを有効にします。
TeamsPremiumLicenseRestricted	Microsoft 365 ユーザーには、Teams Premium ライセンスが割り当てられている必要があります。	SDK を使用して Teams 会議開催者または Microsoft 365 ユーザーに Teams Premium ライセンスを割り当て、このアクションを有効にします。 ターゲット ユーザーは、アクションの種類によって異なります。 Microsoft 365 管理者は、必要なライセンスを割り当てることができます。
ExplicitConsentRequired	アクションを許可するには同意が必要です。	this.call.feature(Features.Recording) または this.call.feature(Features.Transcription) にあるメソッド grantTeamsConsent() を呼び出して、レコーディングまたは文字起こしに同意します。

次のステップ

• ビデオの管理方法を参照する
• 通話の管理方法を参照する
• 通話を記録する方法を参照する