快速入門：建立和管理會議室資源

發行項
08/22/2024

本快速入門可協助您開始使用 Azure 通訊服務會議室。 room 是一個伺服器管理的通訊空間，供一組已知的固定參與者在預定的持續時間內進行協作。會議室概念文件涵蓋了 rooms 的更多詳細資料和使用案例。

物件模型

下表列出物件的主要屬性 room ：

名稱	描述
`roomId`	唯一的 `room` 識別碼。
`validFrom`	`room` 最早可以使用的時間。
`validUntil`	`room` 最晚可以使用的時間。
`pstnDialOutEnabled`	啟用或停用在會議室中撥出 PSTN 號碼。
`participants`	`room` 的參與者清單。指定為 `CommunicationUserIdentifier`。
`roleType`	會議室參與者的角色。可以是 `Presenter`、`Attendee` 或 `Consumer`。

必要條件

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

設定

新增延伸模組

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

az extension add --name communication

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

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

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

setx AZURE_COMMUNICATION_CONNECTION_STRING "<connectionString>"

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

編輯 .zshrc，然後新增環境變數：

export AZURE_COMMUNICATION_CONNECTION_STRING="<connectionString>"

新增環境變數之後，從主控台視窗執行 source ~/.zshrc，讓變更生效。如果您使用 IDE 開啟建立環境變數，您可能需要關閉並重新開啟編輯器、IDE 或殼層，才能存取變數。

編輯 .bash_profile，然後新增環境變數：

export AZURE_COMMUNICATION_CONNECTION_STRING="<connectionString>"

新增環境變數之後，從主控台視窗執行 source ~/.bash_profile，讓變更生效。如果您使用 IDE 開啟建立環境變數，您可能需要關閉並重新開啟編輯器、IDE 或殼層，才能存取變數。

Operations

建立會議室

使用 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。
藉由設定此旗標（“True” 或 “False”）來啟用或停用會議室的 PSTN 撥出，以選擇性地使用 <pstn-dial-out-enabled> 。根據預設，建立會議室時，此旗標會設定為 "False"。

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

az communication rooms create

啟用會議室的 PSTN 撥出功能

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

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> 旗標（“True” 或 “False” ）。

取得會議室

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> 取代為您的會議室識別碼。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
作用中的 Azure 通訊服務資源和連接字串。建立通訊服務資源。
適用於您的作業系統的最新版本 .NET Core 用戶端程式庫。

範例指令碼

您可以在 GitHub (英文) 上檢閱並下載此快速入門的範例程式碼。

設定

建立新的 C# 應用程式

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

dotnet new console -o RoomsQuickstart

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

cd RoomsQuickstart
dotnet build

Install the package

使用 [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 及管理其屬性和生命週期。您的 Communications Service 的連接字串將用來驗證要求。如需連接字串的詳細資訊，請參閱此頁面。


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

建立會議室

設定會議室參與者

若要設定誰可以加入會議室，您必須擁有這些使用者的身分識別清單。您可以遵循此處的指示來建立使用者並核發存取權杖。或者，如果您想要按需要建立使用者，您可以使用 CommunicationIdentityClient 來建立使用者。 ACS 會議室目前僅支援 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 來建立新的 room：

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

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

啟用會議室的 PSTN 撥出功能

預設每個 room 都會停用 PSTN 撥出功能。藉由將 pstnDialOutEnabled 參數定義為 true，即可在 room 建立時啟用它的 PSTN 撥出功能。也可以透過發出 pstnDialOutEnabled 參數的更新要求來修改 room 的這項功能。

// 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 來擷取現有 room 的詳細資料：


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

更新會議室的存留期

藉由發出 ValidFrom 和 ValidUntil 參數的更新要求，即可修改 room 的存留期。會議室的有效期最長為六個月。


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

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

若要將新的參與者新增至 room，請使用用戶端上公開的 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.Attendee };
addOrUpdateParticipants.Add(participant2);
addOrUpdateParticipants.Add(participant3);

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

已新增至 room 的參與者有資格加入通話。已更新的參與者會在通話中看到其新的 role。

取得參與者清單

藉由引用 roomId 來擷取現有 room 的參與者清單：


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

移除參與者

若要從 room 移除參與者並撤銷其存取權，請使用 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");

刪除會議室

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


// 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, Attendee

Removed participants from room

Deleted room with id: 99445276259151407

參考文件

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

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
作用中的 Azure 通訊服務資源和連接字串。建立通訊服務資源。
Java Development Kit (JDK) 第 8 版或更新版本。
Apache Maven

範例指令碼

您可以在 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 通訊室用戶端連結庫。

包括 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
    }
}

初始化會議室用戶端


// 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，請新增下列套件：

<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 來建立新的 room：

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

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

啟用會議室的 PSTN 撥出功能

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 來擷取現有 room 的詳細資料：


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

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

更新會議室的存留期

藉由發出 ValidFrom 和 ValidUntil 參數的更新要求，即可修改 room 的存留期。會議室的有效期最長為六個月。


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

新增或更新參與者

若要對 room 新增或更新參與者，請使用用戶端上公開的 addOrUpdateParticipants 方法。


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

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

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

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

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

已新增至 room 的參與者有資格加入通話。

取得參與者清單

藉由引用 roomId 來擷取現有 room 的參與者清單：


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

移除參與者

若要從 room 移除參與者並撤銷其存取權，請使用 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 通訊服務資源下的所有作用中 rooms。

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

刪除會議室

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


// 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 (Attendee)
8:acs:b6aada1f-0b1d-47ac-866f-91aae00a1d01_00000018-ac89-7c76-35f3-343a0d00e902 (Consumer)

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 通訊服務會議室的全套功能。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
作用中的 Azure 通訊服務資源和連接字串。建立通訊服務資源。
適用於您作業系統的 Python (英文) 3.7+。

範例指令碼

您可以在 GitHub (英文) 上檢閱並下載此快速入門的範例程式碼。

設定

建立新的 Python 應用程式

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

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

Install the package

您必須使用適用於 Python 1.1.0 版或更新版本的 Azure 通訊室用戶端連結庫。

從主控台提示字元中，瀏覽至包含 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()

初始化會議室用戶端

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

建立會議室

設定會議室參與者

若要使用 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 來建立新的 room：

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

由於 rooms 是伺服器端實體，因此您可能會想要追蹤 room.id 並將其保存在所選的儲存媒體中。您可以引用 id 來檢視或更新 room 物件的屬性。

啟用會議室的 PSTN 撥出功能

預設每個 room 都會停用 PSTN 撥出功能。藉由將 pstn_dial_out_enabled 參數定義為 true，即可在 room 建立時啟用它的 PSTN 撥出功能。也可以透過發出 pstn_dial_out_enabled 參數的更新要求來修改 room 的這項功能。

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

取得現有會議室的屬性

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

# 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_from 和 valid_until 參數的更新要求，即可修改 room 的存留期。會議室的有效期最長為六個月。

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

新增或更新參與者

若要在 room 中新增參與者或更新現有的參與者，請使用用戶端上公開的 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.CONSUMER))
    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 的參與者有資格加入通話。

列出會議室中的參與者

藉由引用 room_id 來擷取現有 room 的參與者清單：

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

移除參與者

若要從 room 移除參與者並撤銷其存取權，請使用 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)

刪除會議室

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

# 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 Attendee

Removed participants from room

Deleted room with id: 99445276259151407

參考文件

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

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
作用中的 Azure 通訊服務資源和連接字串。建立通訊服務資源。
最新版的 Node.js (英文) 作用中 LTS 和維護 LTS 版本。

範例指令碼

您可以在 GitHub (英文) 上檢閱並下載此快速入門的範例程式碼。

設定

建立新的 Web 應用程式

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

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

執行 npm init 以使用預設設定建立 package.json 檔案。

npm init -y

建立一個新的檔案 index.js，將在其中新增本快速入門的程式碼。

安裝套件

您必須使用適用於 JavaScript 1.1.0 版或更新版本的 Azure 通訊室用戶端連結庫。

使用 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);
})

初始化會議室用戶端

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

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

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

建立會議室

設定會議室參與者

若要使用 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 來建立新的 room：

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

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

啟用會議室的 PSTN 撥出功能

// 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 來擷取現有 room 的詳細資料：

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

更新會議室的存留期

藉由發出 validFrom 和 validUntil 參數的更新要求，即可修改 room 的存留期。會議室的有效期最長為六個月。

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

新增或更新參與者

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

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

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

已新增至 room 的參與者有資格加入通話。

取得參與者清單

藉由引用 roomId 來擷取現有 room 的參與者清單：

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

移除參與者

若要從 room 移除參與者並撤銷其存取權，請使用 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");

刪除會議室

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

// 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'
}

Removed participants from room

Deleted room with id:  99445276259151407

參考文件

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

下一步

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

在本節中，您已了解如何：

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

您可能也會想要：

了解會議室概念
了解語音和視訊通話概念
檢閱 Azure 通訊服務範例

共用方式為

快速入門：建立和管理會議室資源

物件模型

必要條件

設定

新增延伸模組

登入 Azure CLI

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

Operations

建立會議室

啟用會議室的 PSTN 撥出功能

取得會議室

更新會議室的時間範圍

列出所有作用中的會議室

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

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

從會議室移除參與者

刪除會議室

必要條件

範例指令碼

設定

建立新的 C# 應用程式

Install the package

設定應用程式架構

初始化會議室用戶端

建立會議室

設定會議室參與者

初始化會議室

啟用會議室的 PSTN 撥出功能

取得現有會議室的屬性

更新會議室的存留期

列出所有作用中的會議室

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

取得參與者清單

移除參與者

刪除會議室

執行程式碼

參考文件

必要條件

範例指令碼

設定

建立新的 Java 應用程式

包含套件

包括 BOM 檔案

包括直接相依性

設定應用程式架構

初始化會議室用戶端

建立會議室

設定會議室參與者

初始化會議室

啟用會議室的 PSTN 撥出功能

取得現有會議室的屬性

更新會議室的存留期

新增或更新參與者

取得參與者清單

移除參與者

列出所有作用中的會議室

刪除會議室

執行程式碼

參考文件

必要條件

範例指令碼

設定

建立新的 Python 應用程式

Install the package

設定應用程式架構

初始化會議室用戶端

建立會議室

設定會議室參與者

初始化會議室

啟用會議室的 PSTN 撥出功能

取得現有會議室的屬性

更新會議室的存留期

列出所有作用中的會議室

新增或更新參與者

列出會議室中的參與者

移除參與者

刪除會議室

執行程式碼

參考文件