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

文章
04/19/2024

本快速入門可協助您開始使用 Azure 通訊服務會議室。 room是一個伺服器管理的通訊空間，適用於已知且固定的參與者集，以在預先決定的持續時間內共同作業。會議室概念文件涵蓋的更多詳細數據和使用案例 rooms。

物件模型

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

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

必要條件

具有有效訂用帳戶的 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> 地將參與者類型指定為演示者-參與者、取用者-參與者或出席者參與者。如果您未指定值，則預設值為空白。
以您的 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 撥出功能

透過將參數定義為 --pstn-dial-out-enabled 「True」，即可在期間rooms create啟用 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>"

以ISO8601格式的時間戳取代 <valid-from> ，例如：2022-07-14T10：21，以指定何時開啟會議室以聯結。應該與 --valid-until一起使用。
以ISO8601格式的時間戳取代 <valid-until> ，例如：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> 為您的會議室識別碼。
將、 <participant2><participant3> 取代<participant1>為您稍早取得的使用者識別碼，並使用執行identity user create命令。

刪除會議室

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

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

az communication rooms delete --room "<roomId>"

將取代 <roomId> 為您的會議室識別碼。

必要條件

具有有效訂用帳戶的 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 通訊室用戶端連結庫[]：

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。

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

更新會議室的存留期

發出和 ValidUntil 參數的room更新要求，即可修改的ValidFrom存留期。一個房間最多可以有六個月有效。


// 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 帳戶。免費建立帳戶。
作用中的通訊服務資源和連接字串。建立通訊服務資源。
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());

更新會議室的存留期

發出和 ValidUntil 參數的room更新要求，即可修改的ValidFrom存留期。一個房間最多可以有六個月有效。


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 帳戶。免費建立帳戶。
作用中的通訊服務資源和連接字串。建立通訊服務資源。
適用於您作業系統的 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_until 參數的room更新要求，即可修改的valid_from存留期。一個房間最多可以有六個月有效。

# 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 帳戶。免費建立帳戶。
作用中的通訊服務資源和連接字串。建立通訊服務資源。
最新版的 Node.js Active 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);

更新會議室的存留期

發出和 validUntil 參數的room更新要求，即可修改的validFrom存留期。一個房間最多可以有六個月有效。

// 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 撥出功能

取得現有會議室的屬性

更新會議室的存留期

列出所有使用中會議室

新增或更新參與者

列出會議室中的參與者

拿掉參與者

刪除會議室

執行程式碼

參考文件

必要條件

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