Поделиться через

Краткое руководство. Создание ресурса комнаты и управление ими

  • Статья

Это краткое руководство поможет вам приступить к работе с Службы коммуникации Azure комнатами. A room — это пространство связи, управляемое сервером, для известного фиксированного набора участников для совместной работы в течение предопределенной длительности. Концептуальная документация по комнатам охватывает дополнительные сведения и варианты roomsиспользования.

Объектная модель

В следующей room таблице перечислены основные свойства объектов:

Имя Описание
roomId Уникальный room идентификатор.
validFrom Самое раннее время room можно использовать.
validUntil Последнее room время можно использовать.
pstnDialOutEnabled Включите или отключите исходящий номер ТСОП в комнате.
participants Список участников room. Указан как CommunicationUserIdentifier.
roleType Роль участника комнаты. Может быть либо Presenter, Attendeeлибо Consumer.

Необходимые компоненты

Установка

Добавление расширения

Добавьте расширение Службы коммуникации Azure для Azure CLI с помощью az extension команды.

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> указать тип участника в качестве участника-докладчика, участников-потребителей или участников. Если значение не указано, значение по умолчанию пусто.
  • Замените <connection-string> Службы коммуникации Azure строка подключения.
  • При <valid-from> необходимости следует указать метку времени, когда комната открыта для присоединения, в формате ISO8601, например 2022-07-14T10:21.
  • При <valid-until> необходимости следует указать метку времени, когда номер больше не может быть присоединен, в формате ISO8601, например: 2022-07-14T10:21.
  • Используйте <pstn-dial-out-enabled> при необходимости, установив этот флаг ("True" или "False"), чтобы включить или отключить ТСОП для номера. По умолчанию этот флаг имеет значение False при создании комнаты.

Если вы сохранили строка подключения в переменных среды, как указано выше, вам не потребуется передать их команде.

az communication rooms create

Включение возможности подключения ТСОП для комнаты

ТСОП можно включить во время rooms create , определив --pstn-dial-out-enabled параметр как "True". Эта возможность также может быть изменена --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-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-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 комнатами. A room — это пространство связи, управляемое сервером, для известного фиксированного набора участников для совместной работы в течение предопределенной длительности. Концептуальная документация по комнатам охватывает дополнительные сведения и варианты roomsиспользования.

Необходимые компоненты

Пример кода

Вы можете просмотреть и скачать пример кода для этого краткого запуска на сайте GitHub.

Установка

Создание нового приложения C#

В окне консоли (cmd, PowerShell или Bash) выполните команду dotnet new, чтобы создать консольное приложение с именем RoomsQuickstart. Эта команда создает простой проект "Hello World" на языке C# с одним файлом исходного кода Program.cs.

dotnet new console -o RoomsQuickstart

Измените каталог на только что созданную папку приложения и выполните команду dotnet build, чтобы скомпилировать приложение.

cd RoomsQuickstart
dotnet build

Установка пакета

Установите клиентную библиотеку комнат коммуникации Azure для .NET с [NuGet][https://www.nuget.org/]:

dotnet add package Azure.Communication.Rooms

Вам потребуется использовать клиентскую библиотеку Комнат коммуникации Azure для .NET версии 1.1.0 или более поздней.

Настройка платформы приложения

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

Инициализация комнаты

Создайте новое room с помощью указанного 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);

Так как rooms это серверные сущности, вы можете отслеживать и сохранять их roomId в выбранном хранилище. Вы можете ссылаться на roomId представление или обновление свойств room объекта.

Включение возможности подключения ТСОП для комнаты

По умолчанию для каждого room номера ТСОП отключен. ТСОП можно включить для room создания, определив pstnDialOutEnabled параметр как true. Эта возможность также может быть изменена для параметра room путем выдачи запроса на обновление для 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);

Получение свойств существующей комнаты

Получение сведений о существующем room путем roomIdссылки на :


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

Обновление времени существования комнаты

Время существования room можно изменить путем выдачи запроса на обновление для ValidFrom параметров и ValidUntil параметров. Номер может быть действительным в течение не более шести месяцев.


// 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 в вызове.

Получение списка участников

Получение списка участников для существующего room путем ссылки на 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()}");
}

Удаление участников

Чтобы удалить участника из 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

Справочная документация

Ознакомьтесь с полным набором возможностей Службы коммуникации Azure помещений из справочника по пакету SDK для .NET или справочнике по REST API.

Это краткое руководство поможет вам приступить к работе с Службы коммуникации Azure комнатами. A room — это пространство связи, управляемое сервером, для известного фиксированного набора участников для совместной работы в течение предопределенной длительности. Концептуальная документация по комнатам охватывает дополнительные сведения и варианты roomsиспользования.

Необходимые компоненты

Пример кода

Вы можете просмотреть и скачать пример кода для этого краткого запуска на сайте GitHub.

Установка

Создание нового приложения Java

В окне консоли (cmd, PowerShell или Bash) выполните команду mvn, чтобы создать консольное приложение с именем rooms-quickstart. Эта команда создает простой проект Java Hello World с одним исходным файлом: App.java.

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

Включение пакета

Необходимо использовать клиентская библиотека комнат коммуникации Azure для Java версии 1.1.0 или более поздней.

Включение BOM-файла

Включите в azure-sdk-bom проект зависимость от общедоступной версии библиотеки. В следующем фрагменте кода замените заполнитель {bom_version_to_target} номером версии. Дополнительные сведения о BOM см. в читаемом средстве BOM пакета SDK Azure.

<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 объект, который будет использоваться для создания новых rooms свойств и жизненного цикла и управления ими. Строка подключения будет Communications Service использоваться для проверки подлинности запроса. Дополнительные сведения о строка подключения см. на этой странице.


// 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. Комнаты ACS в настоящее время поддерживают только участника комнаты типа 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));

Инициализация комнаты

Создайте новое room с помощью указанного 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());

Так как rooms это серверные сущности, вы можете отслеживать и сохранять их roomId в выбранном хранилище. Вы можете ссылаться на roomId представление или обновление свойств room объекта.

Включение возможности подключения ТСОП для комнаты

По умолчанию для каждого room номера ТСОП отключен. ТСОП можно включить для room создания, определив pstnDialOutEnabled параметр как true. Эта возможность также может быть изменена для параметра room путем выдачи запроса на обновление для 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());

Получение свойств существующей комнаты

Получение сведений о существующем room путем roomIdссылки на :


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

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

Обновление времени существования комнаты

Время существования room можно изменить путем выдачи запроса на обновление для ValidFrom параметров и ValidUntil параметров. Номер может быть действительным в течение не более шести месяцев.


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 право на присоединение к звонкам.

Получение списка участников

Получение списка участников для существующего room путем ссылки на 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);
}

Удаление участников

Чтобы удалить участника из 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");

Вывод списка всех активных комнат

Извлеките все активные rooms ресурсы Службы коммуникации 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);
}

Удаление комнаты

Если вы хотите распустить существующее 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

Справочная документация

Ознакомьтесь с полным набором возможностей Службы коммуникации Azure комнат из справочника по пакету SDK для Java или справочнике по REST API.

Это краткое руководство поможет вам приступить к работе с Службы коммуникации Azure комнатами. A room — это пространство связи, управляемое сервером, для известного фиксированного набора участников для совместной работы в течение предопределенной длительности. Концептуальная документация по комнатам охватывает дополнительные сведения и варианты roomsиспользования.

Необходимые компоненты

Пример кода

Вы можете просмотреть и скачать пример кода для этого краткого запуска на сайте GitHub.

Установка

Создание приложения Python

В окне терминала или консоли создайте новую папку для приложения и перейдите к ней.

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

Установка пакета

Необходимо использовать клиентская библиотека комнат коммуникации Azure для Python версии 1.1.0 или более поздней.

В командной строке консоли перейдите в каталог, содержащий файл 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 объект, который будет использоваться для создания новых rooms свойств и жизненного цикла и управления ими. Строка подключения будет Communications Service использоваться для проверки подлинности запроса. Дополнительные сведения о строка подключения см. на этой странице.

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

Создание комнаты

Настройка участников комнаты

Чтобы настроить пользователей, которые могут присоединиться к комнате, вам потребуется список удостоверений этих пользователей. Ниже приведены инструкции по созданию пользователей и выдаче маркеров доступа. Кроме того, если вы хотите создать пользователей по запросу, их можно создать с помощью CommunicationIdentityClient. Комнаты ACS в настоящее время поддерживают только участника комнаты типа 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]

Инициализация комнаты

Создайте новое room с помощью указанного 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)

Так как rooms это серверные сущности, вы можете отслеживать и сохранять их room.id в выбранном хранилище. Вы можете ссылаться на id представление или обновление свойств room объекта.

Включение возможности подключения ТСОП для комнаты

По умолчанию для каждого room номера ТСОП отключен. ТСОП можно включить для room создания, определив pstn_dial_out_enabled параметр как true. Эта возможность также может быть изменена для параметра room путем выдачи запроса на обновление для 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)

Обновление времени существования комнаты

Время существования room можно изменить путем выдачи запроса на обновление для valid_from параметров и valid_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)

Добавление или обновление участников

Чтобы добавить новых участников или обновить существующих участников, 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 путем ссылки на 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)

Удаление участников

Чтобы удалить участника из 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

Справочная документация

Ознакомьтесь с полным набором возможностей Службы коммуникации Azure комнат из справочника по пакету SDK для Python или справочнике по REST API.

Это краткое руководство поможет вам приступить к работе с Службы коммуникации Azure комнатами. A room — это пространство связи, управляемое сервером, для известного фиксированного набора участников для совместной работы в течение предопределенной длительности. Концептуальная документация по комнатам охватывает дополнительные сведения и варианты roomsиспользования.

Необходимые компоненты

Пример кода

Вы можете просмотреть и скачать пример кода для этого краткого запуска на сайте GitHub.

Установка

Создание веб-приложения

В окне терминала или консоли создайте новую папку для приложения и перейдите к ней.

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

Выполните команду npm init , чтобы создать файл package.json с параметрами по умолчанию.

npm init -y

Создайте файл index.js , в котором будет добавлен код для этого краткого руководства.

Установка пакетов

Необходимо использовать клиентскую библиотеку Комнат коммуникации Azure для JavaScript версии 1.1.0 или более поздней.

Используйте команду npm install, чтобы установить указанные ниже пакеты SDK Служб коммуникации для JavaScript.

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 объект, который будет использоваться для создания новых rooms свойств и жизненного цикла и управления ими. Строка подключения будет Communications Service использоваться для проверки подлинности запроса. Дополнительные сведения о строка подключения см. на этой странице.

Добавьте следующий код в 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. Комнаты ACS в настоящее время поддерживают только участника комнаты типа 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",
  }
]

Инициализация комнаты

Создайте новое room с помощью указанного 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);

Так как rooms это серверные сущности, вы можете отслеживать и сохранять их roomId в выбранном хранилище. Вы можете ссылаться на roomId представление или обновление свойств room объекта.

Включение возможности подключения ТСОП для комнаты

По умолчанию для каждого room номера ТСОП отключен. ТСОП можно включить для room создания, определив pstnDialOutEnabled параметр как true. Эта возможность также может быть изменена для параметра 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);

Получение свойств существующей комнаты

Получение сведений о существующем room путем roomIdссылки на :

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

Обновление времени существования комнаты

Время существования room можно изменить путем выдачи запроса на обновление для validFrom параметров и validUntil параметров. Номер может быть действительным в течение не более шести месяцев.

// 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 право на присоединение к звонкам.

Получение списка участников

Получение списка участников для существующего 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);
}

Удаление участников

Чтобы удалить участника из 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

Справочная документация

Ознакомьтесь с полным набором возможностей Службы коммуникации Azure помещений из справочника по пакету SDK JavaScript или справочнике по REST API.

Следующие шаги

Вы можете узнать, как присоединиться к телефону после создания и настройки комнаты.

В этом разделе вы узнали, как:

  • Создание комнаты
  • Получение свойств комнаты
  • Обновление свойств комнаты
  • Удаление комнаты

Полезные ссылки