Azure.Communication.Rooms 1.1.0

Azure Communication Rooms 的 .NET 客户端库

此包包含用于 Azure 通信服务库 Rooms 服务的 C# SDK。Azure 通信服务（ACS）Rooms 是一套 API，由 Contoso 服务器应用程序用于创建具有固定生命期和参与者的服务器端管理对话空间，从服务器端预定义规则，确定谁和何时可以进行通信（如预定会议创建）。

随着 ACS Rooms 的一般可用性发布，Contoso 将能够

- Create a meeting space with known time coordinates (validFrom/validUntil)
- Join voice/video calls within that meeting space using the ACS web calling SDK or native mobile calling SDKs
- Add participants to a room
- Assign pre-defined roles to room participants

Rooms 可以最好使用的用例

- Virtual Visits (e.g., telemedicine, remote financial advisor, virtual classroom, etc...)
- Virtual Events (e.g., live event, company all-hands, live concert, etc...)

源代码 | 产品文档 | 示例

入门

安装包

使用 NuGet 安装 Azure Communication Rooms .NET 客户端库

dotnet add package Azure.Communication.Rooms

先决条件

要使用此包，您需要一个Azure订阅和通信服务资源。

要创建新的通信服务，您可以使用Azure门户、Azure PowerShell或.NET管理客户端库。

关键概念

RoomsClient提供创建房间、更新房间、获取房间、列出房间、删除房间、添加参与者、更新参与者、删除参与者和列出参与者的功能。

使用语句

using Azure.Communication.Rooms

身份验证客户端

可以通过从Azure门户中获取的Azure通信资源连接字符串来对房间客户端进行身份验证。

var connectionString = Environment.GetEnvironmentVariable("connection_string") // Find your Communication Services resource in the Azure portal
RoomsClient client = new RoomsClient(connectionString);

示例

创建房间

要创建房间，从RoomsClient中调用CreateRoom或CreateRoomAsync函数。所有参数validFrom、validUntil和participants都是可选的。如果未提供validFrom和validUntil，则validFrom的默认值为当前日期和时间，validUntil的默认值为validFrom + 180天。在定义RoomParticipant时，如果没有指定角色，则默认为Attendee。从1.1.0版本开始，添加了pstnDialOutEnabled以启用房间中的PSTN拨出功能。返回值是Response<CommunicationRoom>，其中包含创建的房间详细信息以及在失败情况下状态和关联的错误代码。

从1.1.0版本开始，ACS房间支持PSTN拨出功能。要使用PSTN拨出属性创建房间，使用createRoomOptions参数调用CreateRoom或CreateRoomAsync函数，将PstnDialOutEnabled设置为true或false。如果没有提供PstnDialOutEnabled，则其默认值为false。此参数包含ValidFrom、ValidUntil、PstnDialOutEnabled和Participants属性。这些属性是可选的。

// Create communication users using the CommunicationIdentityClient
Response<CommunicationUserIdentifier> communicationUser1 = await communicationIdentityClient.CreateUserAsync();
Response<CommunicationUserIdentifier> communicationUser2 = await communicationIdentityClient.CreateUserAsync();

DateTimeOffset validFrom = DateTimeOffset.UtcNow;
DateTimeOffset validUntil = validFrom.AddDays(1);
RoomParticipant participant1 = new RoomParticipant(communicationUser1.Value); // If role is not provided, then it is set as Attendee by default
RoomParticipant participant2 = new RoomParticipant(communicationUser2.Value) { Role = ParticipantRole.Presenter};
List<RoomParticipant> invitedParticipants = new List<RoomParticipant>
{
    participant1,
    participant2
};

Response<CommunicationRoom> createRoomResponse = await roomsClient.CreateRoomAsync(validFrom, validUntil, invitedParticipants);
CommunicationRoom createCommunicationRoom = createRoomResponse.Value;

// Starting in 1.1.0-beta.1 release,CreateRoom function also takes roomCreateOptions as parameter
bool pstnDialOutEnabled = true;
CreateRoomOptions roomCreateOptions = new CreateRoomOptions()
{
    ValidFrom = validFrom,
    ValidUntil = validUntil,
    PstnDialOutEnabled = pstnDialOutEnabled,
    Participants = invitedParticipants
};

createRoomResponse = await roomsClient.CreateRoomAsync(roomCreateOptions);
createCommunicationRoom = createRoomResponse.Value;

更新房间

可以通过从RoomsClient中调用UpdateRoom或UpdateRoomAsync函数来更新创建的房间的validFrom和validUntil属性。

从1.1.0版本开始，ACS房间支持PSTN拨出功能。要更新带PSTN拨出属性的房间，使用updateRoomOptions参数调用UpdateRoom或UpdateRoomAsync函数，并将PstnDialOutEnabled设置为true或false。如果没有提供PstnDialOutEnabled，则房间中的PstnDialOutEnabled属性将不会发生更改。参数包含ValidFrom、ValidUntil和PstnDialOutEnabled属性。这些属性是可选的。

validUntil = validFrom.AddDays(30);
Response<CommunicationRoom> updateRoomResponse = await roomsClient.UpdateRoomAsync(createdRoomId, validFrom, validUntil);
CommunicationRoom updateCommunicationRoom = updateRoomResponse.Value;

// Starting in 1.1.0 release,UpdateRoom function also takes roomCreateOptions as parameter
UpdateRoomOptions roomUpdateOptions = new UpdateRoomOptions()
{
    ValidFrom = validFrom,
    ValidUntil = validUntil,
    PstnDialOutEnabled = pstnDialOutEnabled,
};

updateRoomResponse = await roomsClient.UpdateRoomAsync(createdRoomId, roomUpdateOptions);
updateCommunicationRoom = updateRoomResponse.Value;

获取创建的房间

可以通过从RoomsClient中调用GetRoom或GetRoomAsync函数并传递关联的roomId来获取创建的房间。

Response<CommunicationRoom> getRoomResponse = await roomsClient.GetRoomAsync(createdRoomId);
CommunicationRoom getCommunicationRoom = getRoomResponse.Value;

获取所有房间

可以通过调用RoomsClient中的GetRooms或GetRoomsAsync函数来获取在ACS资源下创建的所有有效房间。

// Retrieve the first 2 pages of active rooms
const int PageSize = 30;
const int PageCount = 2;
int maxRoomCount = PageCount * PageSize;
int counter = 1;

AsyncPageable<CommunicationRoom> allRooms = roomsClient.GetRoomsAsync();
await foreach (CommunicationRoom room in allRooms)
{
    Console.WriteLine($"Room with id {room.Id} is valid from {room.ValidFrom} to {room.ValidUntil}.");
    counter++;

    if (counter == maxRoomCount)
    {
        break;
    }
}

删除房间

要删除房间，请从RoomsClient中调用DeleteRoom或DeleteRoomAsync函数。

Response deleteRoomResponse = await roomsClient.DeleteRoomAsync(createdRoomId);

向房间中添加或更新参与者

为了添加新参与者或更新现有参与者，请从RoomsClient中调用AddOrUpdateParticipants或AddOrUpdateParticipantsAsync函数。

Response<CommunicationUserIdentifier> communicationUser3 = await communicationIdentityClient.CreateUserAsync();
RoomParticipant newParticipant = new RoomParticipant(communicationUser3.Value) { Role = ParticipantRole.Consumer };

// Previous snippet for create room added participant2 as Presenter
participant2 = new RoomParticipant(communicationUser2) { Role = ParticipantRole.Attendee };

List<RoomParticipant> participantsToAddOrUpdate = new List<RoomParticipant>
{
    participant2,   // participant2 updated from Presenter to Attendee
    newParticipant, // newParticipant added to the room
};

Response addOrUpdateParticipantResponse = await roomsClient.AddOrUpdateParticipantsAsync(createdRoomId, participantsToAddOrUpdate);

从房间中删除参与者

要从房间中删除参与者，请从RoomsClient中调用RemoveParticipants或RemoveParticipantsAsync函数。

List<CommunicationIdentifier> participantsToRemove = new List<CommunicationIdentifier>
{
   communicationUser1,
   communicationUser2
};
Response removeParticipantResponse = await roomsClient.RemoveParticipantsAsync(createdRoomId, participantsToRemove);

获取房间中的参与者

要从房间里获取所有参与者，请从RoomsClient调用GetParticipants或GetParticipantsAsync函数。返回的值是Pageable<RoomParticipant>或AsyncPageable<RoomParticipant>，其中包含分页的参与者列表。

AsyncPageable<RoomParticipant> allParticipants = roomsClient.GetParticipantsAsync(createdRoomId);
await foreach (RoomParticipant participant in allParticipants)
{
    Console.WriteLine($" Participant with id {participant.CommunicationIdentifier.RawId} is a {participant.Role}");
}

故障排除

服务响应

对于任何不成功的请求，都会抛出RequestFailedException作为服务响应。异常包含有关从服务返回的响应代码的信息。

try
{
    CommunicationIdentityClient communicationIdentityClient = CreateInstrumentedCommunicationIdentityClient();
    Response<CommunicationUserIdentifier> communicationUser1 = await communicationIdentityClient.CreateUserAsync();
    Response<CommunicationUserIdentifier> communicationUser2 = await communicationIdentityClient.CreateUserAsync();
    DateTimeOffset validFrom = DateTimeOffset.UtcNow;
    DateTimeOffset validUntil = validFrom.AddDays(1);
    List<RoomParticipant> createRoomParticipants = new List<RoomParticipant>();
    RoomParticipant participant1 = new RoomParticipant(communicationUser1.Value) { Role = ParticipantRole.Presenter };
    RoomParticipant participant2 = new RoomParticipant(communicationUser2.Value) { Role = ParticipantRole.Attendee };
    Response<CommunicationRoom> createRoomResponse = await roomsClient.CreateRoomAsync(validFrom, validUntil, createRoomParticipants);
    CommunicationRoom createRoomResult = createRoomResponse.Value;
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.Message);
}

下一步

• 在Azure Communication Services中阅读有关Rooms的更多信息

参与

本项目欢迎贡献和建议。大多数贡献都需要您同意一份贡献者许可协议（CLA），声明您有权并且实际上确实授予我们使用您贡献的权利。有关详细信息，请访问cla.microsoft.com。

本项目已采用Microsoft Open Source Code of Conduct。有关更多信息，请参阅Code of Conduct FAQ或通过[email protected]发送任何额外的问题或评论。

一旦发布SDK，更新示例代码链接