建立會議室資源

本文說明如何在 Azure 通訊服務資源內建立會議室。 一個房間是由伺服器管理的通訊空間,供已知且固定的參與者在預先決定的時間內進行協作。 如需詳細資訊和使用案例,請參閱 結構化會議的會議室 API

物件模型

下表列出會議室物件的主要屬性:

名稱 描述
roomId 唯一會議室識別碼。
validFrom 最早可以使用會議室的時間。
validUntil 最晚可以使用會議室的時間。
pstnDialOutEnabled 啟用或停用從房間撥打至公用電話交換網(PSTN)號碼。
participants 會議室中的參與者清單。 指定為 CommunicationUserIdentifier
roleType 會議室參與者的角色。 可以是 PresenterAttendeeConsumerCollaborator

先決條件

  • 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶
  • 作用中的 Azure 通訊服務資源和連接字串。 建立通訊服務資源
  • 安裝 Azure CLI
  • 您可以按一下設定中的金鑰,從 Azure 入口網站中取得連接字串。

設定

新增延伸模組

使用 az extension 命令新增適用於 Azure CLI 的 Azure 通訊服務延伸模組。

az extension add --name communication

登入 Azure CLI

您必須登入 Azure CLI。 您可以從終端機執行 az login 命令,並提供您的認證來登入。

將連接字串儲存在環境變數中

您可以將 AZURE_COMMUNICATION_CONNECTION_STRING 環境變數設定為使用 Azure CLI 金鑰作業,而不需要使用 --connection_string 傳入連接字串。 若要設定環境變數,請開啟主控台視窗,然後從下列索引標籤選取您的作業系統。 將 <connectionString> 用實際的連接字串取代。

setx AZURE_COMMUNICATION_CONNECTION_STRING "<connectionString>"

新增環境變數之後,您可能需要重新啟動任何需要讀取環境變數的執行中程式,包括主控台視窗。 例如,如果您使用 Visual Studio 作為編輯器,請在執行範例前重新啟動 Visual Studio。

業務

建立會議室

使用 rooms create 命令來建立會議室。

az communication rooms create --presenter-participants "<participantId>" --consumer-participants "<participantId>" --attendee-participant "<participantId>" --valid-from "<valid-from>" --valid-until "<valid-until>" --pstn-dial-out-enabled "<pstn-dial-out-enabled>" --connection-string "<connection-string>"
  • 選擇性地使用 <participantId> 以將參與者類型指定為 presenter-participants、consumer-participants 或 attendee-participants。 如果未指定值,則預設值為空白。
  • 以您的 Azure 通訊服務連接字串取代 <connection-string>
  • 選擇性地使用 <valid-from> 以指定當會議室開放加入時的時間戳記 (以 ISO8601 格式表示),例如:2022-07-14T10:21。
  • 選擇性地使用 <valid-until> 以指定當無法再加入會議室時的時間戳記 (以 ISO8601 格式表示),例如:2022-07-14T10:21。
  • 選擇性地使用 <pstn-dial-out-enabled> (藉由設定此旗標 ("True" 或 "False") 來啟用或停用會議室的 PSTN 撥出)。 根據預設,建立會議室時,此旗標會設定為 "False"。

如果您將連接字串儲存在環境變數中,則不需要將它們傳遞至 命令。

az communication rooms create 

啟用會議室的 PSTN 撥出功能

您可以透過將 rooms create 參數定義為 --pstn-dial-out-enabled,來在 True 期間啟用 PSTN 撥出。 您可以藉由指定 rooms update 參數,在 q --pstn-dial-out-enabled 期間變更這項功能。

az communication rooms create --pstn-dial-out-enabled "<pstn-dial-out-enabled>" --connection-string "<connection-string>"
az communication rooms update --pstn-dial-out-enabled "<pstn-dial-out-enabled>" --room "<roomId>"
  • 若要啟用或停用會議室的 PSTN 撥出,請設定 <pstn-dial-out-enabled> 旗標 (TrueFalse)。

取得會議室

rooms get 命令會傳回現有會議室的屬性。

az communication rooms get --room "<roomId>" 
  • <roomId> 取代為您的會議室識別碼。

更新會議室的時間範圍

您可以更新會議室的時間戳記。 呼叫 room update 命令之前,請確定您已取得具有有效期限的新房間。

az communication rooms update --valid-from "<valid-from>" --valid-until "<valid-until>" --pstn-dial-out-enabled "<pstn-dial-out-enabled>" --room "<roomId>"
  • <valid-from> 取代為 ISO8601 格式的時間戳記 (例如:2022-07-14T10:21),以指定會議室何時開放加入。 應該與 --valid-until 一起使用。
  • <valid-until> 取代為 ISO8601 格式的時間戳記 (例如:2022-07-14T10:21),以指定會議室何時無法再加入。 應該與 --valid-from 一起使用。
  • 取代 <pstn-dial-out-enabled> 來設定此旗標 ("True" 或 "False") 以啟用或停用會議室的 PSTN 撥出功能。 應該與 --pstn-dial-out-enabled 一起使用。
  • <roomId> 取代為您的會議室識別碼。

列出所有作用中的會議室

rooms list 命令會傳回屬於您的 Azure 通訊服務資源的所有作用中會議室。

az communication rooms list

新增參與者或更新現有的參與者

當您建立會議室時,您可以藉由新增參與者或更新其中的現有參與者來更新會議室。 呼叫 room participant add-or-update 命令之前,請確定您已取得新的使用者。

使用 identity user create 命令來建立新的參與者 (由 participantId 識別)。

az communication identity user create

將使用者當作參與者來新增至會議室。

az communication rooms participant add-or-update --attendee-participant "<participantId>" --room "<roomId>"
  • 以您的參與者識別碼取代 <participantId>。 如果會議室中沒有 <participantId>,則該參與者會被新增至會議室作為出席者角色。 否則,該參與者的角色會被更新為出席者角色。
  • <roomId> 取代為您的會議室識別碼。

取得會議室中的參與者清單

az communication rooms participant get --room "<roomId>"
  • <roomId> 取代為您的會議室識別碼。

從會議室移除參與者

您可以使用 rooms participant -remove,從會議室中移除會議室參與者。

az communication rooms participant remove --room "<roomId>" --participants "<participant1>" "<participant2>" "<participant3>"
  • <roomId> 取代為您的會議室識別碼。
  • <participant1><participant2><participant3> 取代為先前透過執行 identity user create 命令取得的使用者識別碼。

刪除會議室

類似於建立會議室,您也可以刪除會議室。

使用 room delete 命令來刪除現有的會議室。

az communication rooms delete --room "<roomId>"
  • <roomId> 取代為您的會議室識別碼。

會議室是伺服器管理的通訊空間,適用於已知、固定的參與者集,以在預先決定的持續時間內共同作業。 如需詳細資訊,請參閱 結構化會議的會議室 API

先決條件

範例程式碼

請在 GitHub 上的 Rooms 快速入門 - .NET 檢視並下載範例程式碼。

設定

建立新的 C# 應用程式

在主控台視窗中 (例如 cmd、PowerShell 或 Bash),使用 dotnet new 命令建立名為 RoomsQuickstart 的新主控台應用程式。 此命令會建立簡單的 "Hello World" C# 專案,內含單一原始程式檔:Program.cs

dotnet new console -o RoomsQuickstart

將您的目錄變更為新建立的應用程式資料夾,然後使用 dotnet build 命令來編譯您的應用程式。

cd RoomsQuickstart
dotnet build

安裝套件

使用 [NuGet][https://www.nuget.org/] 安裝適用於 .NET 的 Azure Communication Rooms 用戶端程式庫:

dotnet add package Azure.Communication.Rooms

使用適用於 .NET 1.1.0 版或更新版本的 Azure 通訊室用戶端連結庫。

設定應用程式架構

Program.cs 檔案中,新增下列程式碼以匯入必要的命名空間,並建立基本程式結構。


using System;
using Azure;
using Azure.Core;
using Azure.Communication.Rooms;

namespace RoomsQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Rooms Quickstart");

            // Quickstart code goes here
        }
    }
}

初始化會議室用戶端

建立新的 RoomsClient 物件,您需要建立新的 rooms 物件,並管理其屬性和生命週期。 使用通訊服務的連接字串來驗證要求。 如需連接字串的詳細資訊,請參閱此頁面


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

建立會議室

設定會議室參與者

若要設定誰可以加入會議室,您必須擁有這些使用者的身分識別清單。 請遵循 存取令牌 中的指示來建立使用者並發出存取令牌。 或者,若要視需要建立使用者,您可以使用CommunicationIdentityClient來建立他們。 Azure 通訊服務會議室目前僅支援類型的 CommunicationUserIdentifier 會議室參與者,使用其他類型的 CommunicationIdentity 會導致運行時錯誤。

若要使用 CommunicationIdentityClient,請安裝下列套件:

dotnet add package Azure.Communication.Identity

另外,在您的 Program.cs 檔案頂端匯入該套件的命名空間:

using Azure.Communication.Identity;

現在,您可以初始化 CommunicationIdentityClient ,並使用它來建立使用者:

// Create identities for users who will join the room
CommunicationIdentityClient identityClient = new CommunicationIdentityClient(connectionString);
CommunicationUserIdentifier user1 = identityClient.CreateUser();
CommunicationUserIdentifier user2 = identityClient.CreateUser();

然後,藉由引用這些使用者來建立會議室參與者清單:

List<RoomParticipant> participants = new List<RoomParticipant>()
{
    new RoomParticipant(user1) { Role = ParticipantRole.Presenter },
    new RoomParticipant(user2) // The default participant role is ParticipantRole.Attendee
};

初始化會議室

使用 participants 上述代碼段中定義的 來建立新的會議室:

// Create a room
DateTimeOffset validFrom = DateTimeOffset.UtcNow;
DateTimeOffset validUntil = validFrom.AddDays(1);
CancellationToken cancellationToken = new CancellationTokenSource().Token;

CommunicationRoom createdRoom = await roomsClient.CreateRoomAsync(validFrom, validUntil, participants, cancellationToken);

// CreateRoom or CreateRoomAsync methods can take CreateRoomOptions type as an input parameter.
bool pstnDialOutEnabled = false;
CreateRoomOptions createRoomOptions = new CreateRoomOptions()
{
    ValidFrom = validFrom,
    ValidUntil = validUntil,
    PstnDialOutEnabled = pstnDialOutEnabled,
    Participants = participants
};

createdRoom = await roomsClient.CreateRoomAsync(createRoomOptions, cancellationToken);
string roomId = createdRoom.Id;
Console.WriteLine("\nCreated room with id: " + roomId);

由於會議室是伺服器端實體,因此您應該追蹤 roomId 並將其保存在所選的儲存媒體中。 您可以參考 roomId 來檢視或更新房間物件的屬性。

啟用會議室的 PSTN 撥出功能

每個房間預設都會停用 PSTN 撥出。 在建立會議室時,您可以通過將參數設定為pstnDialOutEnabled true,來啟用 PSTN 撥出功能。 您可以針對 pstnDialOutEnabled 參數發出更新要求,以變更會議室的功能。

// Create a room
CancellationToken cancellationToken = new CancellationTokenSource().Token;

// CreateRoom or CreateRoomAsync methods to create a room with PSTN dial out capability
bool pstnDialOutEnabled = true;
CreateRoomOptions createRoomOptions = new CreateRoomOptions()
{
    PstnDialOutEnabled = pstnDialOutEnabled,
};

CommunicationRoom createdRoom = await roomsClient.CreateRoomAsync(createRoomOptions, cancellationToken);
Console.WriteLine("\nCreated a room with PSTN dial out enabled: " + createdRoom.PstnDialOutEnabled);

// UpdateRoom or UpdateRoomAsync methods can take UpdateRoomOptions to enable or disable PSTN dial out capability
pstnDialOutEnabled = false;
UpdateRoomOptions updateRoomOptions = new UpdateRoomOptions()
{
    PstnDialOutEnabled = pstnDialOutEnabled,
};

CommunicationRoom updatedRoom = await roomsClient.UpdateRoomAsync(roomId, updateRoomOptions, cancellationToken);
Console.WriteLine("\nUpdated a room with PSTN dial out enabled: " + updatedRoom.PstnDialOutEnabled);

取得現有會議室的屬性

若要擷取現有會議室的詳細數據,請參考 roomId


// Retrieve the room with corresponding ID
CommunicationRoom room = await roomsClient.GetRoomAsync(roomId);
Console.WriteLine("\nRetrieved room with id: " + room.Id);

更新會議室的存留期

您可以通過對ValidFromValidUntil參數提出更新請求來更改房間的有效期限。 會議室的有效期最長為六個月。


// Update room lifetime
DateTimeOffset updatedValidFrom = DateTimeOffset.UtcNow;
DateTimeOffset updatedValidUntil = DateTimeOffset.UtcNow.AddDays(10);
CommunicationRoom updatedRoom = await roomsClient.UpdateRoomAsync(roomId, updatedValidFrom, updatedValidUntil, cancellationToken);

// UpdateRoom or UpdateRoomAsync methods can take UpdateRoomOptions type as an input parameter.
bool pstnDialOutEnabled = true;
UpdateRoomOptions updateRoomOptions = new UpdateRoomOptions()
{
    ValidFrom = validFrom,
    ValidUntil = validUntil,
    PstnDialOutEnabled = pstnDialOutEnabled,
};

updatedRoom = await roomsClient.UpdateRoomAsync(roomId, updateRoomOptions, cancellationToken);
Console.WriteLine("\nUpdated room with validFrom: " + updatedRoom.ValidFrom + ", validUntil: " + updatedRoom.ValidUntil + " and pstnDialOutEnabled: " + updatedRoom.PstnDialOutEnabled);

列出所有作用中的會議室

若要擷取所有作用中的會議室,請使用用戶端上公開的 GetRoomsAsync 方法。


// List all active rooms
AsyncPageable<CommunicationRoom> allRooms = roomsClient.GetRoomsAsync();
await foreach (CommunicationRoom currentRoom in allRooms)
{
    Console.WriteLine("\nFirst room id in all active rooms: " + currentRoom.Id);
    break;
}

新增參與者或更新現有的參與者

若要將新的參與者新增至會議室,請使用 AddParticipantsAsync 用戶端上公開的方法。


List<RoomParticipant> addOrUpdateParticipants = new List<RoomParticipant>();
// Update participant2 from Attendee to Consumer
RoomParticipant participant2 = new RoomParticipant(user2) { Role = ParticipantRole.Consumer };
// Add participant3
CommunicationUserIdentifier user3 = identityClient.CreateUser();
RoomParticipant participant3 = new RoomParticipant(user3) { Role = ParticipantRole.Collaborator };
addOrUpdateParticipants.Add(participant2);
addOrUpdateParticipants.Add(participant3);

Response addOrUpdateParticipantsResponse = await roomsClient.AddOrUpdateParticipantsAsync(roomId, addOrUpdateParticipants);
Console.WriteLine("\nAdded or updated participants to room");

當您將參與者新增至會議室時,他們便有資格加入通話。 已更新的參與者會在通話中看到他們的新 role

取得參與者清單

藉由參考roomId來擷取現有會議室的參與者清單:


// Get list of participants in room
AsyncPageable<RoomParticipant> existingParticipants = roomsClient.GetParticipantsAsync(roomId);
Console.WriteLine("\nRetrieved participants from room: ");
await foreach (RoomParticipant participant in existingParticipants)
{
    Console.WriteLine($"{participant.CommunicationIdentifier.ToString()},  {participant.Role.ToString()}");
}

移除參與者

若要從會議室移除參與者並撤銷其存取權,請使用 RemoveParticipantsAsync 方法。


// Remove user from room
List<CommunicationIdentifier> removeParticipants = new List<CommunicationIdentifier>();
removeParticipants.Add(user2);

Response removeParticipantsResponse = await roomsClient.RemoveParticipantsAsync(roomId, removeParticipants);
Console.WriteLine("\nRemoved participants from room");

刪除會議室

如果您想要解散現有的會議室,請發出明確的刪除要求。 所有房間及其相關資源都會在其有效期限結束後加上寬限期後自動刪除。


// Deletes the specified room
Response deleteRoomResponse = await roomsClient.DeleteRoomAsync(roomId);
Console.WriteLine("\nDeleted room with id: " + roomId);

執行程式碼

若要執行程式代碼,請確定您位於與檔案相同的目錄中 Program.cs


dotnet run

預期的輸出會描述每個已完成的動作:


Azure Communication Services - Rooms Quickstart

Created a room with id: 99445276259151407

Retrieved room with id: 99445276259151407

Updated room with validFrom: 2023-05-11T22:11:46.784Z, validUntil: 2023-05-21T22:16:46.784Z and pstnDialOutEnabled: true

First room id in all active rooms: 99445276259151407

Added or updated participants to room

Retrieved participants from room:
8:acs:b6aada1f-0b1d-47ac-866f-91aae00a1d01_00000018-ac89-7c76-35f3-343a0d00e901, Presenter
8:acs:b6aada1f-0b1d-47ac-866f-91aae00a1d01_00000018-f00d-aa4b-0cf9-9c3a0d00543e, Consumer
8:acs:b6aada1f-0b1d-47ac-866f-91aae00a1d01_00000018-f00d-aaf2-0cf9-9c3a0d00543f, Collaborator

Removed participants from room

Deleted room with id: 99445276259151407

參考文件

請從 .NET SDK 參考REST API 參考中閱讀了解 Azure 通訊服務會議室的全套功能。

會議室是伺服器管理的通訊空間,適用於已知、固定的參與者集,以在預先決定的持續時間內共同作業。 如需詳細資訊,請參閱 結構化會議的會議室 API

先決條件

範例程式碼

Azure 通訊服務 - 會議室 - Java 上,檢閱並下載 GitHub 的範例程式代碼。

設定

建立新的 Java 應用程式

在主控台視窗中 (例如 cmd、PowerShell 或 Bash),使用 mvn 命令建立名為 rooms-quickstart 的新主控台應用程式。 這個指令會建立具有單一原始程式檔的簡單 「Hello World」 Java 專案: App.java

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

包含套件

您需要使用適用於 Java 1.1.0 版或更新版本的 Azure Communication Rooms 用戶端程式庫。

包含 BOM 檔案

包含專案的 azure-sdk-bom ,以相依於連結庫的正式運作 (GA) 版本。 在下列程式碼片段中,將 {bom_version_to_target} 預留位置取代為版本號碼。

若要深入瞭解材料帳單(BOM),請參閱 Azure SDK BOM 自述檔

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然後在相依性區段中包含直接相依性,而不使用版本卷標。

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-rooms</artifactId>
  </dependency>
</dependencies>

包含直接相依性

如果您想要相依於 BOM 中不存在的特定連結庫版本,請將直接相依性新增至您的專案,如下所示。

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-rooms</artifactId>
  <version>1.0.0-beta.1</version>
</dependency>

設定應用程式架構

移至 /src/main/java/com/communication/quickstart 目錄並開啟 App.java 檔案。 新增下列程式碼:


package com.communication.rooms.quickstart;

import com.azure.communication.common.*;
import com.azure.communication.identity.*;
import com.azure.communication.identity.models.*;
import com.azure.core.credential.*;
import com.azure.communication.rooms.*;

import java.io.IOException;
import java.time.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Rooms Quickstart");
        // Quickstart code goes here
    }
}

初始化會議室用戶端

建立新的 RoomsClient 物件,以便用於創建新房間並管理這些房間的屬性和生命週期。 使用通訊服務的連接字串來驗證要求。 如需連接字串的詳細資訊,請參閱 建立通訊資源


// Initialize the rooms client
// Find your Communication Services resource in the Azure portal
String connectionString = "<connection string>";
RoomsClient roomsClient = new RoomsClientBuilder().connectionString(connectionString).buildClient();

建立會議室

設定會議室參與者

若要設定誰可以加入會議室,您必須擁有這些使用者的身分識別清單。 請遵循 存取令牌 中的指示來建立用戶併發出存取令牌。 或者,如果您想要按需要建立使用者,您可以使用 CommunicationIdentityClient 來建立使用者。 Azure 通訊服務會議室目前僅支援類型的 CommunicationUserIdentifier 會議室參與者,使用其他類型的 CommunicationIdentity 會導致運行時錯誤。

若要使用 CommunicationIdentityClient,請新增下列套件:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
</dependency>

在您的 App.java 檔案的頂端匯入該套件:

import com.azure.communication.identity.CommunicationIdentityClient;
import com.azure.communication.identity.CommunicationIdentityClientBuilder;

現在,初始化 CommunicationIdentityClient 並使用它來建立使用者:

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .connectionString(connectionString)
    .buildClient();

CommunicationUserIdentifier user1 = communicationClient.createUser();
CommunicationUserIdentifier user2 = communicationClient.createUser();
CommunicationUserIdentifier user3 = communicationClient.createUser();

然後,藉由引用這些使用者來建立會議室參與者清單:

//The default participant role is ParticipantRole.Attendee
RoomParticipant participant_1 = new RoomParticipant(user1);
RoomParticipant participant_2 = new RoomParticipant(user2);
RoomParticipant participant_3 = new RoomParticipant(user3);

List<RoomParticipant> roomParticipants = new ArrayList<RoomParticipant>();

roomParticipants.add(participant_1);
roomParticipants.add(participant_2.setRole(ParticipantRole.CONSUMER));

初始化會議室

使用 roomParticipants 上述代碼段中定義的 來建立新的會議室:

OffsetDateTime validFrom = OffsetDateTime.now();
OffsetDateTime validUntil = validFrom.plusDays(30);
boolean pstnDialOutEnabled = false;

CreateRoomOptions createRoomOptions = new CreateRoomOptions()
    .setValidFrom(validFrom)
    .setValidUntil(validUntil)
    .setPstnDialOutEnabled(pstnDialOutEnabled)
    .setParticipants(roomParticipants);

CommunicationRoom roomCreated = roomsClient.createRoom(createRoomOptions);

System.out.println("\nCreated a room with id: " + roomCreated.getRoomId());

會議室是伺服器端實體,因此您應該追蹤 roomId 並將其保存在所選的儲存媒體中。 您可以參考 roomId 來檢視或更新房間物件的屬性。

啟用會議室的 PSTN 撥出功能

每個房間預設都會停用 PSTN 撥出。 藉由將 參數定義為 pstnDialOutEnabled true,即可在建立時為會議室啟用 PSTN 撥出。 您可以針對 pstnDialOutEnabled 參數發出更新要求,以變更會議室的功能。

boolean pstnDialOutEnabled = true;
// Create a room with PSTN dial out capability
CreateRoomOptions createRoomOptions = new CreateRoomOptions()
    .setPstnDialOutEnabled(pstnDialOutEnabled)

CommunicationRoom roomCreated = roomsClient.createRoom(createRoomOptions);
System.out.println("\nCreated a room with PSTN dial out enabled: " + roomCreated.getPstnDialOutEnabled());

// Update a room to enable or disable PSTN dial out capability
pstnDialOutEnabled = false;
UpdateRoomOptions updateRoomOptions = new UpdateRoomOptions()
    .setPstnDialOutEnabled(pstnDialOutEnabled);

CommunicationRoom roomUpdated = roomsClient.updateRoom(roomId, updateRoomOptions);
System.out.println("\nUpdated a room with PSTN dial out enabled: " + roomUpdated.getPstnDialOutEnabled());

取得現有會議室的屬性

藉由參考 roomId 來擷取現有會議室的詳細資料:


// Retrieve the room with corresponding ID
CommunicationRoom roomResult = roomsClient.getRoom(roomId);

System.out.println("Retrieved room with id: " + roomResult.getRoomId());

更新會議室的存留期

您可以通過對ValidFromValidUntil參數提出更新請求來更改房間的有效期限。 會議室的有效期最長為六個月。


OffsetDateTime validFrom = OffsetDateTime.now().plusDays(1);
OffsetDateTime validUntil = validFrom.plusDays(1);
boolean pstnDialOutEnabled = true;

UpdateRoomOptions updateRoomOptions = new UpdateRoomOptions()
    .setValidFrom(validFrom)
    .setValidUntil(validUntil)
    .setPstnDialOutEnabled(pstnDialOutEnabled);

CommunicationRoom roomResult = roomsClient.updateRoom(roomId, updateRoomOptions);

System.out.println("Updated room with validFrom: " + roomResult.getValidFrom() + ", validUntil: " + roomResult.getValidUntil() + " and pstnDialOutEnabled: " + roomResult.getPstnDialOutEnabled());

新增或更新參與者

若要將參與者新增或更新至會議室,請使用 addOrUpdateParticipants 用戶端上公開的方法。


List<RoomParticipant> participantsToAddAOrUpdate = new ArrayList<>();

// Updating current participant
participantsToAddAOrUpdate.add(participant_1.setRole(ParticipantRole.PRESENTER));

// Adding new participant
 participantsToAddAOrUpdate.add(participant_3.setRole(ParticipantRole.COLLABORATOR));

AddOrUpdateParticipantsResult addOrUpdateParticipantsResult = roomsClient.addOrUpdateParticipants(roomId, participantsToAddAOrUpdate);

System.out.println("Participant(s) added/updated");

將參與者新增至會議室之後,他們就有資格加入通話。

取得參與者清單

藉由參考roomId來擷取現有會議室的參與者清單:


// Get list of participants
try {

PagedIterable<RoomParticipant> participants = roomsClient.listParticipants(roomId);

System.out.println("Participants:/n");

for (RoomParticipant participant : participants) {
    System.out.println(participant.getCommunicationIdentifier().getRawId() + " (" + participant.getRole() + ")");
   }
} catch (Exception ex) {
    System.out.println(ex);
}

移除參與者

若要從會議室移除參與者並撤銷其存取權,請使用 removeParticipants 方法。


// Remove a participant from the room
List<CommunicationIdentifier> participantsToRemove = new ArrayList<>();

participantsToRemove.add(participant_3.getCommunicationIdentifier());

RemoveParticipantsResult removeParticipantsResult = roomsClient.removeParticipants(roomId,participantsToRemove);

System.out.println("Participant(s) removed");

列出所有作用中的會議室

擷取您的 Azure 通訊服務資源下的所有作用中會議室。

try {
    Iterable<PagedResponse<CommunicationRoom>> roomPages = roomsClient.listRooms().iterableByPage();

    System.out.println("Listing all the rooms IDs in the first two pages of the list of rooms:");

    int count = 0;
    for (PagedResponse<CommunicationRoom> page : roomPages) {
        for (CommunicationRoom room : page.getElements()) {
            System.out.println("\n" + room.getRoomId());
        }

        count++;
        if (count >= 2) {
            break;
        }
    }
} catch (Exception ex) {
    System.out.println(ex);
}

刪除會議室

若要解散現有的會議室,請發出明確的刪除要求。 所有房間及其相關資源都會在其有效期限結束後加上寬限期後自動刪除。


// Deletes the specified room
roomsClient.deleteRoomWithResponse(roomId, Context.NONE);
System.out.println("\nDeleted the room with ID: " + roomId);

執行程式碼

若要執行程式碼,請移至包含 pom.xml 檔案的目錄並對程式進行編譯。

mvn compile

接著,建置套件:

mvn package

執行應用程式。

mvn exec:java -D"exec.mainClass"="com.communication.rooms.quickstart" -D"exec.cleanupDaemonThreads"="false"

預期的輸出會描述每個已完成的動作:

Azure Communication Services - Rooms Quickstart

Created a room with id:  99445276259151407

Retrieved room with id:  99445276259151407

Updated room with validFrom: 2023-05-11T22:11:46.784Z, validUntil: 2023-05-11T22:16:46.784Z and pstnDialOutEnabled: true

Participant(s) added/updated

Participants:
8:acs:b6aada1f-0b1d-47ac-866f-91aae00a1d01_00000018-ac89-7c76-35f3-343a0d00e901 (Presenter)
8:acs:b6aada1f-0b1d-47ac-866f-91aae00a1d01_00000018-ac89-7c76-35f3-343a0d00e902 (Consumer)
8:acs:b6aada1f-0b1d-47ac-866f-91aae00a1d01_00000018-ac89-7c76-35f3-343a0d00e903 (Collaborator)

Participant(s) removed

Listing all the rooms IDs in the first two pages of the list of rooms: 
99445276259151407
99445276259151408
99445276259151409

Deleted the room with ID:  99445276259151407

參考文章

請從 Java SDK 參考REST API 參考中閱讀了解 Azure 通訊服務會議室的全套功能。

會議室是伺服器管理的通訊空間,適用於已知、固定的參與者集,以在預先決定的持續時間內共同作業。 如需詳細資訊,請參閱 結構化會議的會議室 API

先決條件

範例程式碼

檢閱並從 GitHub 的 會議室快速入門 - Python 下載範例程式碼。

設定

建立新的 Python 應用程式

在終端或主控台視窗中,為您的應用程式建立新資料夾並瀏覽至該資料夾。

mkdir acs-rooms-quickstart
cd acs-rooms-quickstart

安裝套件

您需要使用適用於 Python 1.1.0 版或更新版本的 Azure Communication Rooms 用戶端程式庫。

從主控台提示字元中,瀏覽至包含 rooms.py 檔案的目錄,然後執行下列命令:

pip install azure-communication-rooms

設定應用程式架構

建立一個名為 rooms-quickstart.py 的新檔案,並新增基本程式結構。

import os
from datetime import datetime, timedelta
from azure.core.exceptions import HttpResponseError
from azure.communication.rooms import (
    RoomsClient,
    RoomParticipant,
    ParticipantRole
)

class RoomsQuickstart(object):
    print("Azure Communication Services - Rooms Quickstart")
    #room method implementations goes here

if __name__ == '__main__':
    rooms = RoomsQuickstart()

初始化會議室用戶端

建立新的 RoomsClient 物件,以便用於創建新房間並管理這些房間的屬性和生命週期。 使用通訊服務的連接字串來驗證要求。 如需連接字串的詳細資訊,請參閱 建立通訊資源

#Find your Communication Services resource in the Azure portal
connection_string = '<connection_string>'
rooms_client = RoomsClient.from_connection_string(connection_string)

建立會議室

設定會議室參與者

若要設定誰可以加入會議室,您需要這些使用者的身分識別清單。 請遵循 存取令牌 中的指示來建立用戶併發出存取令牌。 或者,若要視需要建立使用者,您可以使用CommunicationIdentityClient來建立他們。 Azure 通訊服務會議室目前僅支援 類型的 CommunicationUserIdentifier會議室參與者。 使用其他類型的 CommunicationIdentity 會導致運行時錯誤。

若要使用 CommunicationIdentityClient,請安裝下列套件:

pip install azure-communication-identity

另外,在您的 rooms-quickstart.py 檔案頂端匯入該套件的命名空間:

from azure.communication.identity import (
    CommunicationIdentityClient
)

現在,初始化 CommunicationIdentityClient 並使用它來建立使用者:

# Create identities for users who will join the room
identity_client = CommunicationIdentityClient.from_connection_string(connection_string)
user1 = identity_client.create_user()
user2 = identity_client.create_user()
user3 = identity_client.create_user()

然後,藉由引用這些使用者來建立會議室參與者清單:

participant_1 = RoomParticipant(communication_identifier=user1, role=ParticipantRole.PRESENTER)
participant_2 = RoomParticipant(communication_identifier=user2, role=ParticipantRole.CONSUMER)
participants = [participant_1, participant_2]

初始化會議室

使用 participants 上述代碼段中定義的 來建立新的會議室:

# Create a room
valid_from = datetime.now()
valid_until = valid_from + timedelta(weeks=4)
pstn_dial_out_enabled = False

try:
    create_room = rooms_client.create_room(
        valid_from=valid_from,
        valid_until=valid_until,
        pstn_dial_out_enabled=pstn_dial_out_enabled,
        participants=participants
    )
    print("\nCreated a room with id: " + create_room.id)
except HttpResponseError as ex:
    print(ex)

由於會議室是伺服器端實體,因此您應該追蹤 room.id 並將其保存在所選的儲存媒體中。 您可以參考 id 來檢視或更新房間物件的屬性。

啟用會議室的 PSTN 撥出功能

每個房間預設都會停用 PSTN 撥出。 在建立會議室時,您可以通過將參數設定為pstn_dial_out_enabled true,來啟用 PSTN 撥出功能。 您可以針對 pstn_dial_out_enabled 參數發出更新要求,以變更會議室的功能。

# Create a room with PSTN dial out capability
pstn_dial_out_enabled = True
create_room = rooms_client.create_room(pstn_dial_out_enabled=pstn_dial_out_enabled)
print("\nCreated room with pstn_dial_out_enabled: " + updated_room.pstn_dial_out_enabled)

# Update a room to enable or disable PSTN dial out capability
pstn_dial_out_enabled= False
updated_room = rooms_client.update_room(room_id=room_id, pstn_dial_out_enabled=pstn_dial_out_enabled)
print("\nUpdated room with pstn_dial_out_enabled: " + updated_room.pstn_dial_out_enabled)

取得現有會議室的屬性

藉由引用 room 來擷取現有 id 的詳細資料:

# Retrieves the room with corresponding ID
room_id = create_room.id
try:
    get_room = rooms_client.get_room(room_id=room_id)
    print("\nRetrieved room with id: ", get_room.id)
except HttpResponseError as ex:
    print(ex)

更新會議室的存留期

您可以通過對valid_fromvalid_until參數提出更新請求來更改房間的有效期限。 會議室的有效期最長為六個月。

# Update the lifetime of a room
valid_from =  datetime.now()
valid_until = valid_from + timedelta(weeks=7)
pstn_dial_out_enabled=True

try:
    updated_room = rooms_client.update_room(room_id=room_id, valid_from=valid_from, valid_until=valid_until, pstn_dial_out_enabled=pstn_dial_out_enabled)
     print("\nUpdated room with validFrom: " + updated_room.valid_from + ", validUntil: " + updated_room.valid_until + " and pstn_dial_out_enabled: " + updated_room.pstn_dial_out_enabled)
except HttpResponseError as ex:
    print(ex)

列出所有作用中的會議室

若要擷取您的資源下所建立的所有作用中會議室,請使用用戶端上公開的 list_rooms 方法。

# List all active rooms
try:
    rooms = rooms_client.list_rooms()
    count = 0
    for room in rooms:
        if count == 1:
            break
        print("\nPrinting the first room in list"
            "\nRoom Id: " + room.id +
            "\nCreated date time: " + str(room.created_at) +
            "\nValid From: " + str(room.valid_from) + 
            "\nValid Until: " + str(room.valid_until) +
            "\nPSTN Dial-Out Enabled: " + str(room.pstn_dial_out_enabled))
        count += 1
except HttpResponseError as ex:
    print(ex)

新增或更新參與者

若要新增參與者或更新會議室中的現有參與者,請使用 add_or_update_participants 用戶端上公開的方法。

# Add or update participants in a room
try:
    # Update existing user2 from consumer to attendee
    participants = []
    participants.append(RoomParticipant(communication_identifier=user2, role=ParticipantRole.ATTENDEE))

    # Add new participant user3
    participants.append(RoomParticipant(communication_identifier=user3, role=ParticipantRole.COLLABORATOR))
    rooms_client.add_or_update_participants(room_id=room_id, participants=participants)
    print("\nAdd or update participants in room")

except HttpResponseError as ex:
    print('Error in adding or updating participants to room.', ex)

當您將參與者新增至會議室時,他們便有資格加入通話。

列出會議室中的參與者

藉由參考room_id來擷取現有會議室的參與者清單:

# Get list of participants in room
try:
    participants = rooms_client.list_participants(room_id)
    print('\nParticipants in Room Id :', room_id)
    for p in participants:
        print(p.communication_identifier.properties['id'], p.role)
except HttpResponseError as ex:
    print(ex)

移除參與者

若要從會議室移除參與者並撤銷其存取權,請使用 remove_participants 方法。

# Remove Participants
try:
    participants = [user2]
    rooms_client.remove_participants(room_id=room_id, participants=participants)
    print("\nRemoved participants from room")

except HttpResponseError as ex:
    print(ex)

刪除會議室

若要解散現有的會議室,請發出明確的刪除要求。 所有會議室及其相關聯的資源都會在其有效期結束加上寬限期後自動刪除。

# Delete Room

rooms_client.delete_room(room_id=room_id)
print("\nDeleted room with id: " + room_id)

執行程式碼

若要執行程式代碼,請確定您位於與檔案 rooms-quickstart.py 相同的目錄中。

python rooms-quickstart.py

預期的輸出會描述每個已完成的動作:

Azure Communication Services - Rooms Quickstart

Created a room with id:  99445276259151407

Retrieved room with id:  99445276259151407

Updated room with validFrom: 2023-05-03T00:00:00+00:00, validUntil: 2023-06-23T00:00:00+00:00 and pstn_dial_out_enabled: True

Printing the first room in list
Room Id: 99445276259151407
Created date time: 2023-05-03T00:00:00+00:00
Valid From: 2023-05-03T00:00:00+00:00
Valid Until: 2023-06-23T00:00:00+00:00
PSTN Dial-Out Enabled: True

Add or update participants in room

Participants in Room Id : 99445276259151407
8:acs:42a0ff0c-356d-4487-a288-ad0aad95d504_00000018-ef00-6042-a166-563a0d0051c1 Presenter
8:acs:42a0ff0c-356d-4487-a288-ad0aad95d504_00000018-ef00-6136-a166-563a0d0051c2 Consumer
8:acs:42a0ff0c-356d-4487-a288-ad0aad95d504_00000018-ef00-61fd-a166-563a0d0051c3 Collaborator

Removed participants from room

Deleted room with id: 99445276259151407

參考文件

請從 Python SDK 參考REST API 參考中閱讀了解 Azure 通訊服務會議室的全套功能。

會議室是伺服器管理的通訊空間,適用於已知、固定的參與者集,以在預先決定的持續時間內共同作業。 如需詳細資訊,請參閱 結構化會議的會議室 API

先決條件

範例程式碼

檢閱並下載 GitHub 上的範例程式碼,請參考 Rooms Quickstart - JavaScript

設定

建立新的 Web 應用程式

在終端或主控台視窗中,為您的應用程式建立新資料夾並瀏覽至該資料夾。

mkdir acs-rooms-quickstart && cd acs-rooms-quickstart

執行 npm init 以建立具有預設設定的 package.json 檔案。

npm init -y

建立新檔案 index.js ,在此範例中新增程序代碼。

安裝套件

您需要使用適用於 JavaScript 1.1.0 版或更新版本的 Azure Communication Rooms 用戶端程式庫。

npm install使用 命令來安裝下列適用於 JavaScript 的通訊服務 SDK。

npm install @azure/communication-rooms --save

設定應用程式架構

index.js 檔案中,新增下列程式碼。 在函式中新增此範例的程式碼 main

const { RoomsClient } = require('@azure/communication-rooms');

const main = async () => {
  console.log("Azure Communication Services - Rooms Quickstart")

  // Quickstart code goes here

};

main().catch((error) => {
  console.log("Encountered an error");
  console.log(error);
})

初始化會議室用戶端

建立新的 RoomsClient 物件,以便用於創建新房間並管理這些房間的屬性和生命週期。 使用通訊服務的連接字串來驗證要求。 如需連接字串的詳細資訊,請參閱 建立通訊資源

index.js 函式內的 main 中新增下列程序碼。

const connectionString =
    process.env["COMMUNICATION_CONNECTION_STRING"] ||
    "endpoint=https://<resource-name>.communication.azure.com/;<access-key>";

// create RoomsClient
const roomsClient = new RoomsClient(connectionString);

建立會議室

設定會議室參與者

若要設定誰可以加入會議室,您必須擁有這些使用者的身分識別清單。 請遵循 存取令牌 中的指示來建立用戶併發出存取令牌。 或者,若要視需要建立使用者,您可以使用CommunicationIdentityClient來建立他們。 Azure 通訊服務會議室目前僅支援類型的 CommunicationUserIdentifier 會議室參與者,使用其他類型的 CommunicationIdentity 會導致運行時錯誤。

若要使用 CommunicationIdentityClient,請安裝下列 npm 套件:

npm install @azure/communication-identity --save

在您的 index.js 檔案頂端,新增以下必要套件。

const { CommunicationIdentityClient } = require('@azure/communication-identity');

現在,初始化 CommunicationIdentityClient 並用它來建立使用者:

// create identities for users
const identityClient = new CommunicationIdentityClient(connectionString);
const user1 = await identityClient.createUserAndToken(["voip"]);
const user2 = await identityClient.createUserAndToken(["voip"]);

然後,藉由引用這些使用者來建立會議室參與者清單:

const participants = [
  {
      id: user1.user,
      role: "Presenter",
  },
  {
    id: user2.user,
    role: "Consumer",
  }
]

初始化會議室

使用 participants 上述代碼段中定義的 來建立新的會議室:

// Create a room
var validFrom = new Date(Date.now());
var validUntil = new Date(validFrom.getTime() + 60 * 60 * 1000);
var pstnDialOutEnabled = false;

const createRoomOptions = {
  validFrom,
  validUntil,
  pstnDialOutEnabled,
  participants
};

const createRoom = await roomsClient.createRoom(createRoomOptions);
const roomId = createRoom.id;
console.log("\nCreated a room with id: ", roomId);

由於會議室是伺服器端實體,因此您應該追蹤 roomId 並將其保存在所選的儲存媒體中。 您可以引用 roomId 來檢視或更新 room 物件的屬性。

啟用會議室的 PSTN 撥出功能

預設每個 room 都會停用 PSTN 撥出功能。 在建立會議室時,您可以通過將參數設定為pstnDialOutEnabled true,來啟用 PSTN 撥出功能。 您也可以透過發出 room 參數的更新要求來變更 pstnDialOutEnabled 的這項功能。

// Create a room with PSTN dial out capability
var pstnDialOutEnabled = true;
const createRoomOptions = {
  pstnDialOutEnabled,
};

const createRoom = await roomsClient.createRoom(createRoomOptions);
console.log("\nCreated a room with PSTN dial out enabled: ", createRoom.pstnDialOutEnabled);

// Update a room to enable or disable PSTN dial out capability
pstnDialOutEnabled = false;
const updateRoomOptions = {
  pstnDialOutEnabled,
};

const updateRoom = await roomsClient.updateRoom(roomId, updateRoomOptions);
console.log("\nUpdated a room with PSTN dial out enabled: ", updateRoom.pstnDialOutEnabled);

取得現有會議室的屬性

藉由參考 roomId 來擷取現有會議室的詳細資料:

// Retrieve the room with corresponding ID
const getRoom = await roomsClient.getRoom(roomId);
console.log("\nRetrieved room with id: ", getRoom.id);

更新會議室的存留期

您可以通過對validFromvalidUntil參數提出更新請求來更改房間的有效期限。 會議室的有效期最長為六個月。

// Update room lifetime
validFrom.setTime(validUntil.getTime());
validUntil.setTime(validFrom.getTime() + 5 * 60 * 1000);
pstnDialOutEnabled = true;
// request payload to update a room
const updateRoomOptions = {
  validFrom,
  validUntil,
  pstnDialOutEnabled,
};

const updateRoom = await roomsClient.updateRoom(roomId, updateRoomOptions);
console.log("\nUpdated room with validFrom: ", updateRoom.validFrom, ", validUntil: ", updateRoom.validUntil, " and pstnDialOutEnabled: ", updateRoom.pstnDialOutEnabled);

取得會議室清單

使用 listRooms 方法來擷取房間清單:

const roomsList = await roomsClient.listRooms();
console.log("\nRetrieved list of rooms; printing first room:");
for await (const currentRoom of roomsList) {
  // access room data here
  console.log(currentRoom);
  break;
}

新增或更新參與者

若要將新的參與者新增至會議室,請使用 addOrUpdateParticipants 用戶端上公開的方法。 若會議室中已存在參與者,這個方法也會更新該參與者。

// Add and update participants

const user3 = await identityClient.createUserAndToken(["voip"]);

// request payload to add and update participants
const addOUpdateParticipantsList = [
  {
      id: user1.user,
      role: "Presenter",
  },
  {
    id: user3.user,
    role: "Collaborator",
  }
]

// add user3 to the room and update user1 to Presenter role
await roomsClient.addOrUpdateParticipants(roomId, addOUpdateParticipantsList);
console.log("\nAdded and updated participants in the room");

將參與者新增至會議室之後,他們就有資格加入通話。

取得參與者清單

藉由參考roomId來擷取現有會議室的參與者清單:

const participantsList = await roomsClient.listParticipants(roomId);
console.log("\nRetrieved participants for room:");
for await (const participant of participantsList) {
  // access participant data here
  console.log(participant);
}

移除參與者

若要從會議室移除參與者並撤銷其存取權,請使用 removeParticipants 方法。

// Remove both users from the room
const removeParticipantsList = [user1.user, user2.user]

// remove both users from the room with the request payload
await roomsClient.removeParticipants(roomId, removeParticipantsList);
console.log("\nRemoved participants from room");

刪除會議室

如果您想要解散現有的會議室,您可以發出明確的刪除要求。 所有房間及其相關資源都會在其有效期限結束後加上寬限期後自動刪除。

// Deletes the specified room
await roomsClient.deleteRoom(roomId);
console.log("\nDeleted room with id: ", roomId)

執行程式碼

若要執行程式代碼,請確定您位於與檔案 index.js 相同的目錄中。

node index.js

預期的輸出會描述每個已完成的動作:

Azure Communication Services - Rooms QuickStart

Created a room with id:  99445276259151407

Retrieved room with id:  99445276259151407

Updated room with validFrom:  2023-05-11T22:11:46.784Z, validUntil:  2023-05-11T22:16:46.784Z and pstnDialOutEnabled: true

Retrieved list of rooms; printing first room:

{
  id: "99445276259151407",
  createdAt: "2023-05-11T22:11:50.784Z",
  validFrom: "2023-05-11T22:11:46.784Z",
  validUntil: "2023-05-11T22:16:46.784Z"
}

Added and updated participants in the room

Retrieved participants for room:
{
  id: {
    kind: 'communicationUser',
    communicationUserId: '8:acs:b6aada1f-0b1d-47ac-866f-91aae00a1d01_00000018-ac89-7c76-35f3-343a0d00e901'
  },
  role: 'Presenter'
}
{
  id: {
    kind: 'communicationUser',
    communicationUserId: '8:acs:b6aada1f-0b1d-47ac-866f-91aae00a1d01_00000018-ac89-7ccc-35f3-343a0d00e902'
  },
  role: 'Consumer'
}
{
  id: {
    kind: 'communicationUser',
    communicationUserId: '8:acs:b6aada1f-0b1d-47ac-866f-91aae00a1d01_00000018-ac89-7ccc-35f3-343a0d00e903'
  },
  role: 'Collaborator'
}

Removed participants from room

Deleted room with id:  99445276259151407

參考文件

請從 JavaScript SDK 參考REST API 參考中閱讀了解 Azure 通訊服務會議室的全套功能。

後續步驟

您可以在建立和設定會議室之後,了解如何加入會議室通話

本文說明如何:

  • 建立新的會議室
  • 取得會議室的屬性
  • 更新會議室的屬性
  • 刪除會議室