Biblioteca de clientes das Salas de Comunicação do Azure para .NET – versão 1.0.0

  • Artigo

Esse pacote contém um SDK do C# para o Serviço de Salas do Serviços de Comunicação do Azure. Serviços de Comunicação do Azure (ACS) Rooms é um conjunto de APIs, usado por aplicativos de servidor contoso para criar um espaço de conversa gerenciado pelo servidor com conjunto fixo de tempo de vida e participantes, definindo previamente regras da camada de servidor quem e quando podem se comunicar (como a criação de reunião agendada).

Com a versão de disponibilidade geral das Salas do ACS, a Contoso poderá:

- 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

O main cenários em que as Salas podem ser melhor usadas:

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

Código-fonte | Documentação do produto | Amostras

Introdução

Instalar o pacote

Instale a biblioteca de clientes das Salas de Comunicação do Azure para .NET com o NuGet:

dotnet add package Azure.Communication.Rooms

Pré-requisitos

Você precisa de uma assinatura do Azure e um Recurso do Serviço de Comunicação para usar esse pacote.

Para criar um novo Serviço de Comunicação, você pode usar o Portal do Azure, o Azure PowerShell ou a biblioteca de clientes de gerenciamento do .NET.

Principais conceitos

RoomsClient fornece a funcionalidade para criar sala, atualizar sala, obter sala, listar salas, excluir sala, adicionar participantes, atualizar participantes, remover participantes e listar participantes.

Como usar instruções

using Azure.Communication.Rooms

Autenticar o cliente

Os clientes de salas podem ser autenticados usando a cadeia de conexão adquirida de um Recurso de Comunicação do Azure no Portal do Azure.

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

Exemplos

Criar uma sala

Para criar uma sala, chame a CreateRoom função ou CreateRoomAsync de RoomsClient. Os validFromargumentos , validUntile participants são todos opcionais. Se validFrom e validUntil não forem fornecidos, o padrão para validFrom será a data e hora atual e o padrão para validUntil será validFrom + 180 days. Ao definir RoomParticipant, se a função não for especificada, ela será Attendee por padrão. O valor retornado é Response<CommunicationRoom> que contém os detalhes da sala criada, bem como a status e os códigos de erro associados em caso de falha.

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

Atualizar uma sala

As validFrom propriedades e validUntil de uma sala criada podem ser atualizadas chamando a UpdateRoom função ou UpdateRoomAsync de RoomsClient.

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

Obter uma sala criada

Uma sala criada pode ser recuperada chamando a GetRoom função ou GetRoomAsync de RoomsClient e passando o associado roomId.

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

Obter todas as salas

Todas as salas válidas criadas em um recurso do ACS podem ser recuperadas chamando a GetRooms função ou GetRoomsAsync de RoomsClient.

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

Excluir sala

Para excluir uma sala, chame a DeleteRoom função ou DeleteRoomAsync de RoomsClient.

Response deleteRoomResponse = await roomsClient.DeleteRoomAsync(createdRoomId);

Adicionar ou atualizar participantes em uma sala

Para adicionar novos participantes ou atualizar participantes existentes, chame a AddOrUpdateParticipants função ou AddOrUpdateParticipantsAsync de RoomsClient.

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

Remover participantes em uma sala

Para remover participantes de uma sala, chame a RemoveParticipants função ou RemoveParticipantsAsync de RoomsClient.

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

Obter participantes em uma sala

Para obter todos os participantes de uma sala, chame a GetParticipants função ou GetParticipantsAsync de RoomsClient. O valor retornado é Pageable<RoomParticipant> ou AsyncPageable<RoomParticipant> que contém a lista paginada de participantes.

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

Solução de problemas

Respostas de serviço

Um RequestFailedException é gerado como uma resposta de serviço para solicitações malsucedidas. A exceção contém informações sobre qual código de resposta foi retornado do serviço.

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

Próximas etapas

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Atualizar os links de código de exemplo depois que o sdk for publicado