Schnellstart: Erstellen und Verwalten einer Raumressource

Name	Beschreibung
`roomId`	Eindeutiger `room`-Bezeichner.
`validFrom`	Der früheste Zeitpunkt, zu dem ein `room` verwendet werden kann.
`validUntil`	Der letzte Zeitpunkt, zu dem ein `room` verwendet werden kann.
`pstnDialOutEnabled`	Aktivieren oder Deaktivieren von Ausgehenden Anrufen an eine PSTN-Nummer in einem Raum.
`participants`	Teilnehmerliste für `room`. Angegeben als `CommunicationUserIdentifier`.
`roleType`	Die Rolle eines Teilnehmers für einen Raum. Kann `Presenter`, `Attendee` oder `Consumer` lauten.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Eine aktive Communication Services-Ressource und eine Verbindungszeichenfolge. Erstellen Sie eine Communication Services-Ressource.
Installieren Sie die Azure-Befehlszeilenschnittstelle.
Sie können die Verbindungszeichenfolge aus dem Azure-Portal abrufen, indem Sie in den Einstellungen auf die Schlüssel klicken.

Einrichten

Hinzufügen der Erweiterung

Fügen Sie die Azure Communication Services-Erweiterung für Azure CLI mithilfe des Befehls az extension hinzu.

az extension add --name communication

Sie müssen sich bei der Azure-Befehlszeilenschnittstelle anmelden. Sie können sich anmelden, indem Sie den az login-Befehl im Terminal ausführen und Ihre Anmeldedaten eingeben.

Speichern der Verbindungszeichenfolge in einer Umgebungsvariablen

Sie können die Umgebungsvariable AZURE_COMMUNICATION_CONNECTION_STRING so konfigurieren, dass Azure CLI-Schlüsselvorgänge verwendet werden, ohne dass Sie --connection_string zum Übergeben der Verbindungszeichenfolge verwenden müssen. Öffnen Sie zum Konfigurieren einer Umgebungsvariablen ein Konsolenfenster, und wählen Sie über die folgenden Registerkarten Ihr Betriebssystem aus. Ersetzen Sie <connectionString> durch Ihre Verbindungszeichenfolge.

setx AZURE_COMMUNICATION_CONNECTION_STRING "<connectionString>"

Nachdem Sie die Umgebungsvariable hinzugefügt haben, müssen Sie möglicherweise alle ausgeführten Programme neu starten, die die Umgebungsvariablen lesen müssen, einschließlich des Konsolenfensters. Wenn Sie beispielsweise Visual Studio als Editor verwenden, müssen Sie Visual Studio neu starten, bevor Sie das Beispiel ausführen.

Bearbeiten Sie .zshrc, und fügen Sie die Umgebungsvariable hinzu:

export AZURE_COMMUNICATION_CONNECTION_STRING="<connectionString>"

Führen Sie nach dem Hinzufügen der Umgebungsvariablen im Konsolenfenster source ~/.zshrc aus, damit die Änderungen wirksam werden. Wenn Sie die Umgebungsvariable bei geöffneter IDE erstellt haben, müssen Sie den Editor, die IDE oder die Shell unter Umständen schließen und erneut öffnen, um auf die Variable zuzugreifen.

Bearbeiten Sie .bash_profile, und fügen Sie die Umgebungsvariable hinzu:

export AZURE_COMMUNICATION_CONNECTION_STRING="<connectionString>"

Führen Sie nach dem Hinzufügen der Umgebungsvariablen im Konsolenfenster source ~/.bash_profile aus, damit die Änderungen wirksam werden. Wenn Sie die Umgebungsvariable bei geöffneter IDE erstellt haben, müssen Sie den Editor, die IDE oder die Shell unter Umständen schließen und erneut öffnen, um auf die Variable zuzugreifen.

Operations

Erstellen eines Raums

Erstellen Sie mit dem rooms create-Befehl einen Raum.

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>"

Verwenden Sie optional <participantId>, um den Typ des Teilnehmers als Presenter-Teilnehmer, Consumer-Teilnehmer oder einfachen Teilnehmer anzugeben. Wenn Sie keinen Wert angeben, ist der Standardwert leer.
Ersetzen Sie <connection-string> durch Ihre Azure Communication Services-Verbindungszeichenfolge.
Verwenden Sie optional <valid-from>, um den Zeitstempel, wenn der Raum für die Teilnahme geöffnet ist, im ISO8601-Format anzugeben, z. B.: 2022-07-14T10:21.
Verwenden Sie optional <valid-until>, um den Zeitstempel, wenn kein Beitreten zum Raum mehr möglich ist, im ISO8601-Format anzugeben, z. B.: 2022-07-14T10:21.
Verwenden Sie <pstn-dial-out-enabled> optional durch Setzen dieses Flags („True“ oder „False“), um die PSTN-Auswahl für einen Raum zu aktivieren oder zu deaktivieren. Standardmäßig ist dieses Kennzeichen beim Erstellen eines Raums auf „False“ festgelegt.

Wenn Sie die Verbindungszeichenfolge wie oben beschrieben in Umgebungsvariablen gespeichert haben, ist keine Übergabe an den Befehl erforderlich.

az communication rooms create

Aktivieren der PSTN-Auswahlfunktion für einen Raum

Die PSTN-Auswahl kann während rooms create aktiviert werden, indem der Parameter --pstn-dial-out-enabled als „True“ definiert wird. Diese Funktion kann auch während rooms update durch Angabe des Parameters --pstn-dial-out-enabled geändert werden.

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>"

Setzen Sie das <pstn-dial-out-enabled>-Flag („True“ oder „False“), um die PSTN-Auswahl für einen Raum zu aktivieren oder zu deaktivieren.

Abrufen der Räume

Der rooms get-Befehl gibt die Attribute eines vorhandenen Raums zurück.

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

Ersetzen Sie <roomId> durch Ihre Raum-ID.

Aktualisieren des Zeitraums für einen Raum

Sie können den Zeitstempel eines Raums aktualisieren. Vergewissern Sie sich vor dem Aufrufen des room update-Befehls, dass Sie einen neuen Raum mit einem gültigen Zeitrahmen erworben haben.

az communication rooms update --valid-from "<valid-from>" --valid-until "<valid-until>" --pstn-dial-out-enabled "<pstn-dial-out-enabled>" --room "<roomId>"

Ersetzen Sie <valid-from> durch den Zeitstempel im ISO8601-Format (Beispiel: 2022-07-14T10:21), um anzugeben, wann der Raum für die Teilnahme geöffnet ist. Sollte zusammen mit --valid-until verwendet werden.
Ersetzen Sie <valid-until> durch den Zeitstempel im ISO8601-Format (Beispiel: 2022-07-14T10:21), um anzugeben, wann ein Beitreten zum Raum nicht mehr möglich ist. Sollte zusammen mit --valid-from verwendet werden.
Ersetzen Sie <pstn-dial-out-enabled>, um dieses Flag zu setzen („True“ oder „False“), um die PSTN-Auswahl für einen Raum zu aktivieren oder zu deaktivieren. Sollte zusammen mit --pstn-dial-out-enabled verwendet werden.
Ersetzen Sie <roomId> durch Ihre Raum-ID.

Liste aller aktiven Räume

Der Befehl rooms list gibt alle aktiven Räume zurück, die zu Ihrer Azure Communication Services-Ressource gehören.

az communication rooms list

Hinzufügen neuer Teilnehmer oder Aktualisieren vorhandener Teilnehmer

Wenn Sie einen Raum erstellen, können Sie den Raum aktualisieren, indem Sie einen neuen Teilnehmer hinzufügen oder einen vorhandenen Teilnehmer darin aktualisieren. Vergewissern Sie sich vor dem Aufrufen des Befehls room participant add-or-update, dass Sie über einen neuen Benutzer verfügen.

Verwenden Sie den identity user create-Befehl, um einen neuen Teilnehmer zu erstellen, der durch participantId bezeichnet wird.

az communication identity user create

Fügen Sie einen Benutzer zum Raum als Teilnehmer hinzu.

az communication rooms participant add-or-update --attendee-participant "<participantId>" --room "<roomId>"

Ersetzen Sie <participantId> durch Ihre Teilnehmer-ID. Wenn <participantId> nicht im Raum vorhanden ist, wird der Teilnehmer dem Raum in der Teilnehmerrolle hinzugefügt. Andernfalls wird die Rolle des Teilnehmers in eine Teilnehmerrolle aktualisiert.
Ersetzen Sie <roomId> durch Ihre Raum-ID.

Abrufen der Teilnehmerliste in einem Raum

az communication rooms participant get --room "<roomId>"

Ersetzen Sie <roomId> durch Ihre Raum-ID.

Entfernen eines Teilnehmers aus einem Raum

Sie können einen Raumteilnehmer mit rooms participant -remove aus einem Raum entfernen.

az communication rooms participant remove --room "<roomId>" --participants "<participant1>" "<participant2>" "<participant3>"

Ersetzen Sie <roomId> durch Ihre Raum-ID.
Ersetzen Sie <participant1>, <participant2>, <participant3> durch Ihre Benutzer-ID, die Sie zuvor durch Ausführen des Befehls identity user create abgerufen haben.

Löschen eines Raums

Ähnlich wie beim Erstellen eines Raums können Sie einen Raum auch löschen.

Verwenden Sie den Befehl room delete, um den vorhandenen Raum zu löschen.

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

Ersetzen Sie <roomId> durch Ihre Raum-ID.

Diese Schnellstartanleitung erleichtert Ihnen den Einstieg in Azure Communication Services-Räume. Ein room ist ein vom Server verwalteter Kommunikationsraum für eine bekannte, feste Gruppe von Teilnehmer*innen, die über einen vordefinierten Zeitraum zusammenarbeiten können. In der konzeptionellen Dokumentation zu den Räumen werden weitere Details und Anwendungsfälle für rooms behandelt.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Eine aktive Communication Services-Ressource und eine Verbindungszeichenfolge. Erstellen Sie eine Communication Services-Ressource.
Die aktuelle Version der .NET Core-Clientbibliothek für Ihr Betriebssystem.

Beispielcode

Sie können den Beispielcode für diesen Schnellstart auf GitHub überprüfen und herunterladen.

Einrichten

Erstellen einer neuen C#-Anwendung

Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen RoomsQuickstart. Dieser Befehl erstellt ein einfaches „Hallo Welt“-C#-Projekt mit einer einzigen Quelldatei: Program.cs.

dotnet new console -o RoomsQuickstart

Wechseln Sie zum neu erstellten App-Ordner, und verwenden Sie den Befehl dotnet build, um Ihre Anwendung zu kompilieren.

cd RoomsQuickstart
dotnet build

Installieren des Pakets

Installieren der .NET-Clientbibliothek für Räume von Azure Communication Services mit [NuGet][https://www.nuget.org/]:

dotnet add package Azure.Communication.Rooms

Sie müssen die Azure Communication Rooms-Clientbibliothek für Räume für .NET Version 1.1.0 oder höher verwenden.

Einrichten des App-Frameworks

Fügen Sie in der Program.cs-Datei den folgenden Code hinzu, um die erforderlichen Namespaces zu importieren und die grundlegende Programmstruktur zu erstellen.


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

Initialisieren eines Raumclients

Erstellen Sie ein neues RoomsClient-Objekt, das verwendet wird, um neue rooms zu erstellen und deren Eigenschaften und Lebenszyklus zu verwalten. Die Verbindungszeichenfolge von Communications Service wird verwendet, um die Anforderung zu authentifizieren. Weitere Informationen zu Verbindungszeichenfolgen finden Sie auf dieser Seite.


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

Erstellen eines Raums

Einrichten von Raumteilnehmern

Um einzurichten, wer einem Raum beitreten kann, benötigen Sie die Liste der Identitäten dieser Benutzer. Sie können die hier beschriebenen Anweisungen zum Erstellen von Benutzern und Ausstellen von Zugriffstoken befolgen. Wenn Sie die Benutzer bei Bedarf erstellen möchten, können Sie sie auch mit CommunicationIdentityClient erstellen. ACS-Räume unterstützen derzeit nur einen Raumteilnehmer vom Typ „CommunicationUserIdentifier“. Die Verwendung anderer CommunicationIdentity-Typen führt zu einem Laufzeitfehler.

Um CommunicationIdentityClient zu verwenden, installieren Sie das folgende Paket:

dotnet add package Azure.Communication.Identity

Importieren Sie außerdem den Namespace des Pakets am Anfang der Program.cs-Datei:

using Azure.Communication.Identity;

Jetzt kann CommunicationIdentityClient initialisiert und zum Erstellen von Benutzern verwendet werden:

// Create identities for users who will join the room
CommunicationIdentityClient identityClient = new CommunicationIdentityClient(connectionString);
CommunicationUserIdentifier user1 = identityClient.CreateUser();
CommunicationUserIdentifier user2 = identityClient.CreateUser();

Erstellen Sie dann die Liste der Raumteilnehmer, indem Sie auf diese Benutzer verweisen:

List<RoomParticipant> participants = new List<RoomParticipant>()
{
    new RoomParticipant(user1) { Role = ParticipantRole.Presenter },
    new RoomParticipant(user2) // The default participant role is ParticipantRole.Attendee
};

Initialisieren des Raums

Erstellen Sie eine neue room mit dem oben im Codeausschnitt definierten 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);

Da es sich bei rooms um serverseitige Entitäten handelt, müssen Sie die roomId nachverfolgen und auf dem Speichermedium Ihrer Wahl speichern. Sie können auf die roomId verweisen, um die Eigenschaften eines room-Objekts anzuzeigen oder zu aktualisieren.

Aktivieren der PSTN-Auswahlfunktion für einen Raum

Für jede room ist die PSTN-Auswahl standardmäßig deaktiviert. Die PSTN-Auswahl kann für ein room bei der Erstellung aktiviert werden, indem Sie den Parameter pstnDialOutEnabled als „true“ definieren. Diese Funktion kann auch für eine room geändert werden, indem eine Aktualisierungsanforderung für den pstnDialOutEnabled Parameter ausgestellt wird.

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

Abrufen von Eigenschaften eines vorhandenen Raums

Rufen Sie die Details eines vorhandenen room ab, indem Sie auf die roomId verweisen:


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

Aktualisieren der Lebensdauer eines Raums

Die Lebensdauer eines room kann geändert werden, indem eine Aktualisierungsanforderung für die Parameter ValidFrom und ValidUntil ausgegeben wird. Ein Raum kann maximal sechs Monate lang gültig sein.


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

Liste aller aktiven Räume

Um alle aktiven Räume abzurufen, verwenden Sie die GetRoomsAsync-Methode, die auf dem Client verfügbar gemacht wird.


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

Hinzufügen neuer Teilnehmer oder Aktualisieren vorhandener Teilnehmer

Verwenden Sie zum Hinzufügen neuer Teilnehmer zu room die Methode AddParticipantsAsync, die auf dem Client verfügbar gemacht wird.


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

Teilnehmer*innen, die einem room hinzugefügt wurden, können an Anrufen teilnehmen. Teilnehmer, die aktualisiert wurden, sehen ihre neue role im Aufruf.

Abrufen der Teilnehmerliste

Rufen Sie die Liste von Teilnehmern eines vorhandenen room ab, indem Sie auf roomId verweisen:


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

Entfernen von Teilnehmer*innen

Wenn Sie einen Teilnehmer aus einem room entfernen und seinen Zugriff widerrufen möchten, verwenden Sie die Methode 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");

Raum löschen

Wenn Sie einen vorhanden room auflösen möchten, können Sie eine explizite Löschanforderung ausgeben. Alle rooms und die zugehörigen Ressourcen werden nach Ablauf ihrer Gültigkeitsdauer und einer Toleranzperiode automatisch gelöscht.


// Deletes the specified room
Response deleteRoomResponse = await roomsClient.DeleteRoomAsync(roomId);
Console.WriteLine("\nDeleted room with id: " + roomId);

Ausführen des Codes

Vergewissern Sie sich, dass Sie sich in dem Verzeichnis befinden, in dem sich die Program.cs-Datei befindet, um den Code auszuführen.


dotnet run

In der erwarteten Ausgabe wird jede abgeschlossene Aktion beschrieben:


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

Referenzdokumentation

Lesen Sie mehr zu den vollständigen Funktionen von Azure Communication Services-Räumen in der .NET SDK-Referenz oder REST-API-Referenz.

Diese Schnellstartanleitung erleichtert Ihnen den Einstieg in Azure Communication Services-Räume. Ein room ist ein vom Server verwalteter Kommunikationsraum für eine bekannte, feste Gruppe von Teilnehmer*innen, die über einen vordefinierten Zeitraum zusammenarbeiten können. In der konzeptionellen Dokumentation zu den Räumen werden weitere Details und Anwendungsfälle für rooms behandelt.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Eine aktive Communication Services-Ressource und eine Verbindungszeichenfolge. Erstellen Sie eine Communication Services-Ressource.
Java Development Kit (JDK), Version 8 oder höher.
Apache Maven

Beispielcode

Sie können den Beispielcode für diesen Schnellstart auf GitHub überprüfen und herunterladen.

Einrichten

Erstellen einer neuen Java-Anwendung

Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl mvn zum Erstellen einer neuen Konsolen-App mit dem Namen rooms-quickstart. Dieser Befehl erstellt ein einfaches Java-Projekt vom Typ „Hallo Welt“ mit einer einzelnen Quelldatei: App.java.

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

Einschließen des Pakets

Sie müssen die Azure Communication Rooms-Clientbibliothek für Räume für Java Version 1.1.0 oder höher verwenden.

BOM-Datei einfügen

Fügen Sie azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit der allgemein verfügbaren Version der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur BOM finden Sie in der Azure SDK-BOM-Infodatei.

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

und fügen Sie dann die direkte Abhängigkeit ohne Versions-Tag in den Abschnitt „Abhängigkeit“ ein.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-rooms</artifactId>
  </dependency>
</dependencies>

Direkte Abhängigkeiten einfügen

Wenn Sie eine Abhängigkeit von einer bestimmten Version der Bibliothek übernehmen möchten, die nicht in der BOM vorhanden ist, fügen Sie ihrem Projekt die direkte Abhängigkeit wie folgt hinzu.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-communication-rooms</artifactId>
  <version>1.0.0-beta.1</version>
</dependency>

Einrichten des App-Frameworks

Wechseln Sie zum Verzeichnis „/src/main/java/com/communication/quickstart“, und öffnen Sie die App.java-Datei. Fügen Sie den folgenden Code hinzu:


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

Initialisieren eines Raumclients

Erstellen Sie ein neues RoomsClient-Objekt, das verwendet wird, um neue rooms zu erstellen und deren Eigenschaften und Lebenszyklus zu verwalten. Die Verbindungszeichenfolge von Communications Service wird verwendet, um die Anforderung zu authentifizieren. Weitere Informationen zu Verbindungszeichenfolgen finden Sie auf dieser Seite.


// Initialize the rooms client
// Find your Communication Services resource in the Azure portal
String connectionString = "<connection string>";
RoomsClient roomsClient = new RoomsClientBuilder().connectionString(connectionString).buildClient();

Erstellen eines Raums

Einrichten von Raumteilnehmern

Um einzurichten, wer einem Raum beitreten kann, benötigen Sie die Liste der Identitäten dieser Benutzer. Sie können die hier beschriebenen Anweisungen zum Erstellen von Benutzern und Ausstellen von Zugriffstoken befolgen. Wenn Sie die Benutzer bei Bedarf erstellen möchten, können Sie sie auch mit CommunicationIdentityClient erstellen. ACS-Räume unterstützen derzeit nur einen Raumteilnehmer vom Typ „CommunicationUserIdentifier“. Die Verwendung anderer CommunicationIdentity-Typen führt zu einem Laufzeitfehler.

Fügen Sie das folgende Paket hinzu, um CommunicationIdentityClient zu verwenden:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
</dependency>

Importieren Sie das Paket oben in Ihre App.java-Datei:

import com.azure.communication.identity.CommunicationIdentityClient;
import com.azure.communication.identity.CommunicationIdentityClientBuilder;

Jetzt kann CommunicationIdentityClient initialisiert und zum Erstellen von Benutzern verwendet werden:

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .connectionString(connectionString)
    .buildClient();

CommunicationUserIdentifier user1 = communicationClient.createUser();
CommunicationUserIdentifier user2 = communicationClient.createUser();
CommunicationUserIdentifier user3 = communicationClient.createUser();

Erstellen Sie dann die Liste der Raumteilnehmer, indem Sie auf diese Benutzer verweisen:

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

Initialisieren des Raums

Erstellen Sie eine neue room mit dem oben im Codeausschnitt definierten 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());

Da es sich bei rooms um serverseitige Entitäten handelt, müssen Sie die roomId nachverfolgen und auf dem Speichermedium Ihrer Wahl speichern. Sie können auf die roomId verweisen, um die Eigenschaften eines room-Objekts anzuzeigen oder zu aktualisieren.

Aktivieren der PSTN-Auswahlfunktion für einen Raum

Für jede room ist die PSTN-Auswahl standardmäßig deaktiviert. Die PSTN-Auswahl kann für ein room bei der Erstellung aktiviert werden, indem Sie den Parameter pstnDialOutEnabled als „true“ definieren. Diese Funktion kann auch für eine room geändert werden, indem eine Aktualisierungsanforderung für den pstnDialOutEnabled Parameter ausgestellt wird.

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

Abrufen von Eigenschaften eines vorhandenen Raums

Rufen Sie die Details eines vorhandenen room ab, indem Sie auf die roomId verweisen:


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

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

Aktualisieren der Lebensdauer eines Raums

Die Lebensdauer eines room kann geändert werden, indem eine Aktualisierungsanforderung für die Parameter ValidFrom und ValidUntil ausgegeben wird. Ein Raum kann maximal sechs Monate lang gültig sein.


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

Hinzufügen oder Aktualisieren von Teilnehmern

Verwenden Sie zum Hinzufügen oder Aktualisieren neuer Teilnehmer zu room die Methode addOrUpdateParticipants, die auf dem Client verfügbar gemacht wird.


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

Teilnehmer*innen, die einem room hinzugefügt wurden, können an Anrufen teilnehmen.

Abrufen der Teilnehmerliste

Rufen Sie die Liste von Teilnehmern eines vorhandenen room ab, indem Sie auf roomId verweisen:


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

Entfernen von Teilnehmer*innen

Wenn Sie einen Teilnehmer aus einem room entfernen und seinen Zugriff widerrufen möchten, verwenden Sie die Methode 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");

Liste aller aktiven Räume

Rufen Sie alle aktiven rooms unter Ihrer Azure Communication Services-Ressource ab.

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

Raum löschen

Wenn Sie einen vorhanden room auflösen möchten, können Sie eine explizite Löschanforderung ausgeben. Alle rooms und die zugehörigen Ressourcen werden nach Ablauf ihrer Gültigkeitsdauer und einer Toleranzperiode automatisch gelöscht.


// Deletes the specified room
roomsClient.deleteRoomWithResponse(roomId, Context.NONE);
System.out.println("\nDeleted the room with ID: " + roomId);

Ausführen des Codes

Navigieren Sie zum Ausführen des Codes zum Verzeichnis, das die pom.xml-Datei enthält, und kompilieren Sie das Programm.


mvn compile

Erstellen Sie dann das Paket:


mvn package

Führen Sie die Anwendung aus.

mvn exec:java -D"exec.mainClass"="com.communication.rooms.quickstart" -D"exec.cleanupDaemonThreads"="false"

In der erwarteten Ausgabe wird jede abgeschlossene Aktion beschrieben:


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

Referenzdokumentation

Lesen Sie mehr zu den vollständigen Funktionen von Azure Communication Services-Räumen in der Java SDK-Referenz oder REST-API-Referenz.

Diese Schnellstartanleitung erleichtert Ihnen den Einstieg in Azure Communication Services-Räume. Ein room ist ein vom Server verwalteter Kommunikationsraum für eine bekannte, feste Gruppe von Teilnehmer*innen, die über einen vordefinierten Zeitraum zusammenarbeiten können. In der konzeptionellen Dokumentation zu den Räumen werden weitere Details und Anwendungsfälle für rooms behandelt.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Eine aktive Communication Services-Ressource und eine Verbindungszeichenfolge. Erstellen Sie eine Communication Services-Ressource.
Python 3.7 oder höher für Ihr Betriebssystem

Beispielcode

Sie können den Beispielcode für diesen Schnellstart auf GitHub überprüfen und herunterladen.

Einrichten

Erstellen einer neuen Python-Anwendung

Erstellen Sie in einem Terminal- oder Konsolenfenster einen neuen Ordner für Ihre Anwendung, und navigieren Sie zu diesem Verzeichnis.

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

Installieren des Pakets

Sie müssen die Azure Communication Rooms-Clientbibliothek für Räume für Python Version 1.1.0 oder höher verwenden.

Wechseln Sie in der Eingabeaufforderung der Konsole zum Verzeichnis, das die Datei „rooms.py“ enthält. Führen Sie dann den folgenden Befehl aus:

pip install azure-communication-rooms

Einrichten des App-Frameworks

Erstellen Sie eine neue Datei namens rooms-quickstart.py, und fügen Sie die grundlegende Programmstruktur hinzu.

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

Initialisieren eines Raumclients

Erstellen Sie ein neues RoomsClient-Objekt, das verwendet wird, um neue rooms zu erstellen und deren Eigenschaften und Lebenszyklus zu verwalten. Die Verbindungszeichenfolge von Communications Service wird verwendet, um die Anforderung zu authentifizieren. Weitere Informationen zu Verbindungszeichenfolgen finden Sie auf dieser Seite.

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

Erstellen eines Raums

Einrichten von Raumteilnehmern

Um einzurichten, wer einem Raum beitreten kann, benötigen Sie die Liste der Identitäten dieser Benutzer. Sie können die hier beschriebenen Anweisungen zum Erstellen von Benutzern und Ausstellen von Zugriffstoken befolgen. Wenn Sie die Benutzer bei Bedarf erstellen möchten, können Sie sie auch mit CommunicationIdentityClient erstellen. ACS-Räume unterstützen derzeit nur einen Raumteilnehmer vom Typ „CommunicationUserIdentifier“. Die Verwendung anderer CommunicationIdentity-Typen führt zu einem Laufzeitfehler.

Um CommunicationIdentityClient zu verwenden, installieren Sie das folgende Paket:

pip install azure-communication-identity

Importieren Sie außerdem den Namespace des Pakets am Anfang der rooms-quickstart.py-Datei:

from azure.communication.identity import (
    CommunicationIdentityClient
)

Jetzt kann CommunicationIdentityClient initialisiert und zum Erstellen von Benutzern verwendet werden:

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

Erstellen Sie dann die Liste der Raumteilnehmer, indem Sie auf diese Benutzer verweisen:

participant_1 = RoomParticipant(communication_identifier=user1, role=ParticipantRole.PRESENTER)
participant_2 = RoomParticipant(communication_identifier=user2, role=ParticipantRole.CONSUMER)
participants = [participant_1, participant_2]

Initialisieren des Raums

Erstellen Sie eine neue room mit dem oben im Codeausschnitt definierten 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)

Da es sich bei rooms um serverseitige Entitäten handelt, müssen Sie die room.id nachverfolgen und auf dem Speichermedium Ihrer Wahl speichern. Sie können auf die id verweisen, um die Eigenschaften eines room-Objekts anzuzeigen oder zu aktualisieren.

Aktivieren der PSTN-Auswahlfunktion für einen Raum

Für jede room ist die PSTN-Auswahl standardmäßig deaktiviert. Die PSTN-Auswahl kann für ein room bei der Erstellung aktiviert werden, indem Sie den Parameter pstn_dial_out_enabled als „true“ definieren. Diese Funktion kann auch für eine room geändert werden, indem eine Aktualisierungsanforderung für den pstn_dial_out_enabled Parameter ausgestellt wird.

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

Abrufen von Eigenschaften eines vorhandenen Raums

Rufen Sie die Details eines vorhandenen room ab, indem Sie auf die id verweisen:

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

Aktualisieren der Lebensdauer eines Raums

Die Lebensdauer eines room kann geändert werden, indem eine Aktualisierungsanforderung für die Parameter valid_from und valid_until ausgegeben wird. Ein Raum kann maximal sechs Monate lang gültig sein.

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

Liste aller aktiven Räume

Um alle aktiven Räume abzurufen, die unter Ihrer Ressource erstellt wurden, verwenden Sie die list_rooms-Methode, die auf dem Client verfügbar gemacht wird.

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

Hinzufügen oder Aktualisieren von Teilnehmern

Verwenden Sie die add_or_update_participants-Methode, die auf dem Client verfügbar gemacht wird, um neue Teilnehmer hinzuzufügen oder vorhandene Teilnehmer in einem room zu aktualisieren.

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

Teilnehmer*innen, die einem room hinzugefügt wurden, können an Anrufen teilnehmen.

Auflisten der Teilnehmer an einem Raum

Rufen Sie die Liste von Teilnehmern eines vorhandenen room ab, indem Sie auf room_id verweisen:

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

Entfernen von Teilnehmer*innen

Wenn Sie einen Teilnehmer aus einem room entfernen und seinen Zugriff widerrufen möchten, verwenden Sie die Methode 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)

Raum löschen

Wenn Sie einen vorhanden room auflösen möchten, können Sie eine explizite Löschanforderung ausgeben. Alle rooms und die zugehörigen Ressourcen werden nach Ablauf ihrer Gültigkeitsdauer und einer Toleranzperiode automatisch gelöscht.

# Delete Room

rooms_client.delete_room(room_id=room_id)
print("\nDeleted room with id: " + room_id)

Ausführen des Codes

Vergewissern Sie sich, dass Sie sich in dem Verzeichnis befinden, in dem sich die rooms-quickstart.py-Datei befindet, um den Code auszuführen.


python rooms-quickstart.py

In der erwarteten Ausgabe wird jede abgeschlossene Aktion beschrieben:


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

Referenzdokumentation

Lesen Sie mehr zu den vollständigen Funktionen von Azure Communication Services-Räumen in der Python SDK-Referenz oder REST-API-Referenz.

Diese Schnellstartanleitung erleichtert Ihnen den Einstieg in Azure Communication Services-Räume. Ein room ist ein vom Server verwalteter Kommunikationsraum für eine bekannte, feste Gruppe von Teilnehmer*innen, die über einen vordefinierten Zeitraum zusammenarbeiten können. In der konzeptionellen Dokumentation zu den Räumen werden weitere Details und Anwendungsfälle für rooms behandelt.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Eine aktive Communication Services-Ressource und eine Verbindungszeichenfolge. Erstellen Sie eine Communication Services-Ressource.
Die aktuellen Versionen von Node.js. Active LTS- und Maintenance LTS Versionen

Beispielcode

Sie können den Beispielcode für diesen Schnellstart auf GitHub überprüfen und herunterladen.

Einrichten

Erstellen einer neuen Webanwendung

Erstellen Sie in einem Terminal- oder Konsolenfenster einen neuen Ordner für Ihre Anwendung, und navigieren Sie zu diesem Verzeichnis.

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

Führen Sie npm init aus, um die Datei package.json mit den Standardeinstellungen zu erstellen.

npm init -y

Erstellen Sie eine neue index.js-Datei, in der der Code für diesen Schnellstart hinzugefügt wird.

Installieren der Pakete

Sie müssen die Azure Communication Rooms-Clientbibliothek für JavaScript Version 1.1.0 oder höher verwenden.

Verwenden Sie den Befehl npm install, um die unten angegebenen Communication Services-SDKs für JavaScript zu installieren.

npm install @azure/communication-rooms --save

Einrichten des App-Frameworks

Fügen Sie in der Datei index.js den folgenden Code hinzu. Wir fügen den Code für den Schnellstart in der main-Funktion hinzu.

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

Initialisieren eines Raumclients

Erstellen Sie ein neues RoomsClient-Objekt, das verwendet wird, um neue rooms zu erstellen und deren Eigenschaften und Lebenszyklus zu verwalten. Die Verbindungszeichenfolge von Communications Service wird verwendet, um die Anforderung zu authentifizieren. Weitere Informationen zu Verbindungszeichenfolgen finden Sie auf dieser Seite.

Fügen Sie in index.js innerhalb der main-Funktion den folgenden Code hinzu.

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

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

Erstellen eines Raums

Einrichten von Raumteilnehmern

Um einzurichten, wer einem Raum beitreten kann, benötigen Sie die Liste der Identitäten dieser Benutzer. Sie können die hier beschriebenen Anweisungen zum Erstellen von Benutzern und Ausstellen von Zugriffstoken befolgen. Wenn Sie die Benutzer bei Bedarf erstellen möchten, können Sie sie auch mit CommunicationIdentityClient erstellen. ACS-Räume unterstützen derzeit nur einen Raumteilnehmer vom Typ „CommunicationUserIdentifier“. Die Verwendung anderer CommunicationIdentity-Typen führt zu einem Laufzeitfehler.

Installieren Sie das folgende npm-Paket, um CommunicationIdentityClient zu verwenden:

npm install @azure/communication-identity --save

Fügen Sie außerdem das folgende erforderliche Paket oben in Ihrer index.js-Datei hinzu:

const { CommunicationIdentityClient } = require('@azure/communication-identity');

Jetzt kann CommunicationIdentityClient initialisiert und zum Erstellen von Benutzern verwendet werden:

// create identities for users
const identityClient = new CommunicationIdentityClient(connectionString);
const user1 = await identityClient.createUserAndToken(["voip"]);
const user2 = await identityClient.createUserAndToken(["voip"]);

Erstellen Sie dann die Liste der Raumteilnehmer, indem Sie auf diese Benutzer verweisen:

const participants = [
  {
      id: user1.user,
      role: "Presenter",
  },
  {
    id: user2.user,
    role: "Consumer",
  }
]

Initialisieren des Raums

Erstellen Sie eine neue room mit dem oben im Codeausschnitt definierten 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);

Da es sich bei rooms um serverseitige Entitäten handelt, müssen Sie die roomId nachverfolgen und auf dem Speichermedium Ihrer Wahl speichern. Sie können auf die roomId verweisen, um die Eigenschaften eines room-Objekts anzuzeigen oder zu aktualisieren.

Aktivieren der PSTN-Auswahlfunktion für einen Raum

Für jede room ist die PSTN-Auswahl standardmäßig deaktiviert. Die PSTN-Auswahl kann für ein room bei der Erstellung aktiviert werden, indem Sie den Parameter pstnDialOutEnabled als „true“ definieren. Diese Funktion kann auch für eine room geändert werden, indem eine Aktualisierungsanforderung für den pstnDialOutEnabled Parameter ausgestellt wird.

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

Abrufen von Eigenschaften eines vorhandenen Raums

Rufen Sie die Details eines vorhandenen room ab, indem Sie auf die roomId verweisen:

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

Aktualisieren der Lebensdauer eines Raums

Die Lebensdauer eines room kann geändert werden, indem eine Aktualisierungsanforderung für die Parameter validFrom und validUntil ausgegeben wird. Ein Raum kann maximal sechs Monate lang gültig sein.

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

Abrufen der Liste der Räume

Rufen Sie Ihre Liste der Räume mithilfe der listRooms-Methode ab:

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

Hinzufügen oder Aktualisieren von Teilnehmern

Verwenden Sie zum Hinzufügen neuer Teilnehmer zu room die Methode addOrUpdateParticipants, die auf dem Client verfügbar gemacht wird. Diese Methode aktualisiert auch Teilnehmer, die bereits im Raum vorhanden sind.

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

Teilnehmer*innen, die einem room hinzugefügt wurden, können an Anrufen teilnehmen.

Abrufen der Teilnehmerliste

Rufen Sie die Liste von Teilnehmern eines vorhandenen room ab, indem Sie auf roomId verweisen:

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

Entfernen von Teilnehmer*innen

Wenn Sie einen Teilnehmer aus einem room entfernen und seinen Zugriff widerrufen möchten, verwenden Sie die Methode 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");

Raum löschen

Wenn Sie einen vorhanden room auflösen möchten, können Sie eine explizite Löschanforderung ausgeben. Alle rooms und die zugehörigen Ressourcen werden nach Ablauf ihrer Gültigkeitsdauer und einer Toleranzperiode automatisch gelöscht.

// Deletes the specified room
await roomsClient.deleteRoom(roomId);
console.log("\nDeleted room with id: ", roomId)

Ausführen des Codes

Vergewissern Sie sich, dass Sie sich in dem Verzeichnis befinden, in dem sich die index.js-Datei befindet, um den Code auszuführen.

node index.js

In der erwarteten Ausgabe wird jede abgeschlossene Aktion beschrieben:

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

Referenzdokumentation

Lesen Sie mehr zu den vollständigen Funktionen von Azure Communication Services-Räumen in der JavaScript SDK-Referenz oder REST-API-Referenz.

Freigeben über

Objektmodell

Voraussetzungen

Einrichten

Hinzufügen der Erweiterung

Anmelden bei der Azure-Befehlszeilenschnittstelle

Speichern der Verbindungszeichenfolge in einer Umgebungsvariablen

Operations

Erstellen eines Raums

Aktivieren der PSTN-Auswahlfunktion für einen Raum

Abrufen der Räume

Aktualisieren des Zeitraums für einen Raum

Liste aller aktiven Räume

Hinzufügen neuer Teilnehmer oder Aktualisieren vorhandener Teilnehmer

Abrufen der Teilnehmerliste in einem Raum

Entfernen eines Teilnehmers aus einem Raum

Löschen eines Raums

Voraussetzungen

Beispielcode

Einrichten

Erstellen einer neuen C#-Anwendung

Installieren des Pakets

Einrichten des App-Frameworks

Initialisieren eines Raumclients

Erstellen eines Raums

Einrichten von Raumteilnehmern

Initialisieren des Raums

Aktivieren der PSTN-Auswahlfunktion für einen Raum

Abrufen von Eigenschaften eines vorhandenen Raums

Aktualisieren der Lebensdauer eines Raums

Liste aller aktiven Räume

Hinzufügen neuer Teilnehmer oder Aktualisieren vorhandener Teilnehmer

Abrufen der Teilnehmerliste

Entfernen von Teilnehmer*innen

Raum löschen

Ausführen des Codes

Referenzdokumentation

Voraussetzungen

Beispielcode

Einrichten

Erstellen einer neuen Java-Anwendung

Einschließen des Pakets

BOM-Datei einfügen

Direkte Abhängigkeiten einfügen

Einrichten des App-Frameworks

Initialisieren eines Raumclients

Erstellen eines Raums

Einrichten von Raumteilnehmern

Initialisieren des Raums

Aktivieren der PSTN-Auswahlfunktion für einen Raum

Abrufen von Eigenschaften eines vorhandenen Raums

Aktualisieren der Lebensdauer eines Raums

Hinzufügen oder Aktualisieren von Teilnehmern

Abrufen der Teilnehmerliste

Entfernen von Teilnehmer*innen

Liste aller aktiven Räume

Raum löschen

Ausführen des Codes

Referenzdokumentation

Voraussetzungen

Beispielcode

Einrichten

Erstellen einer neuen Python-Anwendung

Installieren des Pakets

Einrichten des App-Frameworks

Initialisieren eines Raumclients

Erstellen eines Raums

Einrichten von Raumteilnehmern

Initialisieren des Raums

Aktivieren der PSTN-Auswahlfunktion für einen Raum

Abrufen von Eigenschaften eines vorhandenen Raums

Aktualisieren der Lebensdauer eines Raums

Liste aller aktiven Räume

Hinzufügen oder Aktualisieren von Teilnehmern

Auflisten der Teilnehmer an einem Raum

Entfernen von Teilnehmer*innen

Raum löschen

Ausführen des Codes

Referenzdokumentation