Schnellstart: Zugreifen auf TURN-Relays

Wichtig

Dieses Feature von Azure Communication Services befindet sich derzeit in der Public Preview-Phase. Preview-APIs und -SDKs werden ohne Vereinbarung zum Servicelevel bereitgestellt und sind nicht für Produktionsworkloads vorgesehen. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.

In dieser Schnellstartanleitung erfahren Sie, wie Sie ein Netzwerk-Relaytoken für den Zugriff auf TURN-Server von Azure Communication Services abrufen.

Voraussetzungen

  • Ein Azure-Konto mit einem aktiven Abonnement. Kostenlos ein Konto erstellen
  • Eine aktive Azure Communication Services-Ressource. Informationen zum Erstellen einer Communication Services-Ressource finden Sie bei Bedarf hier.

Prüfen der Voraussetzungen

  • Führen Sie in einem Terminal- oder Befehlsfenster den Befehl dotnet aus, um sich zu vergewissern, dass das ,NET SDK installiert ist.

Einrichten

Erstellen einer neuen C#-Anwendung

  1. Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen RelayTokenQuickstart. Dieser Befehl erstellt ein einfaches „Hallo Welt“-C#-Projekt mit einer einzigen Quelldatei: Program.cs.
dotnet new console -o RelayTokenQuickstart
  1. Wechseln Sie zum neu erstellten App-Ordner, und verwenden Sie den Befehl dotnet build, um Ihre Anwendung zu kompilieren.
cd RelayTokenQuickstart
dotnet build

Installieren des Pakets

Installieren Sie im Anwendungsverzeichnis mithilfe des Befehls dotnet add package die Azure Communication Services Identity- und NetworkTraversal-Bibliothek für das .NET-Paket.

dotnet add package Azure.Communication.Identity
dotnet add package Azure.Communication.NetworkTraversal

Einrichten des App-Frameworks

Über das Projektverzeichnis:

  1. Öffnen Sie die Datei Program.cs in einem Text-Editor.
  2. Fügen Sie eine using-Anweisung hinzu, um Azure.Communication.Identity, System.Threading.Tasks und System.Net.Http einzuschließen
  3. Aktualisieren der Main-Methodendeklaration zur Unterstützung von asynchronem Code

Der Code lautet wie folgt:

using System;
using Azure.Communication.Identity;
using Azure;
using System.Collections.Generic;
using Azure.Communication.NetworkTraversal;

namespace RelayTokenQuickstart
{
    class Program
    {
        static async Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - User Relay Token Quickstart");

            // Quickstart code goes here
        }
    }
}

Authentifizieren des Clients

Initialisieren Sie einen Kommunikationsidentitätsclient (CommunicationIdentityClient) mit Ihrer Verbindungszeichenfolge. Im folgenden Code wird die Verbindungszeichenfolge für die Ressource aus einer Umgebungsvariablen abgerufen. Wenn Sie die Umgebungsvariable nach dem Start der Anwendung erstellt haben, müssen der Editor, die IDE oder die Shell, in dem bzw. der sie ausgeführt wird, geschlossen und erneut geöffnet werden, damit der Zugriff auf die Variable möglich ist.

Fügen Sie der Main-Methode folgenden Code hinzu:

// This code demonstrates how to fetch your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
var client = new CommunicationIdentityClient(connectionString);

Erstellen einer Identität

Von Azure Communication Services wird ein einfaches Identitätsverzeichnis gepflegt. Verwenden Sie die Methode createUser, um in dem Verzeichnis einen neuen Eintrag mit einer eindeutigen Id zu erstellen. Speichern Sie die empfangene Identität mit einer Zuordnung zu den Benutzern Ihrer Anwendung. Beispielsweise, indem Sie sie in der Datenbank des Anwendungsservers speichern. Die Identität ist später erforderlich, um Zugriffstoken auszustellen.

var identityResponse = await client.CreateUserAsync();
var identity = identityResponse.Value;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");

Austauschen des Benutzerzugriffstokens gegen ein Relaytoken

Rufen Sie den Azure Communication-Tokendienst auf, um das Benutzerzugriffstoken gegen ein TURN-Diensttoken zu tauschen

var relayClient = new CommunicationRelayClient("COMMUNICATION_SERVICES_CONNECTION_STRING");

Response<CommunicationRelayConfiguration> turnTokenResponse = await relayClient.GetRelayConfigurationAsync(identity);
DateTimeOffset turnTokenExpiresOn = turnTokenResponse.Value.ExpiresOn;
IReadOnlyList<CommunicationTurnServer> turnServers = turnTokenResponse.Value.TurnServers;
Console.WriteLine($"Expires On: {turnTokenExpiresOn}");
foreach (CommunicationTurnServer turnServer in turnServers)
{
    foreach (string url in turnServer.Urls)
    {
        Console.WriteLine($"TURN Url: {url}");
    }
    Console.WriteLine($"TURN Username: {turnServer.Username}");
    Console.WriteLine($"TURN Credential: {turnServer.Credential}");
}

Ausführen des Codes

Führen Sie die Anwendung mit dem Befehl dotnet run aus dem Anwendungsverzeichnis aus.

dotnet run

Einrichten

Erstellen einer neuen Node.js-Anwendung

Öffnen Sie Ihr Terminal- oder Befehlsfenster, erstellen Sie ein neues Verzeichnis für Ihre App, und navigieren Sie zu diesem Verzeichnis.

mkdir relay-token-quickstart && cd relay-token-quickstart

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

npm init -y

Installieren des Pakets

Verwenden Sie den Befehl npm install, um die Clientbibliothek für Identitäten von Azure Communication Services sowie die Network Traversal-Bibliothek für JavaScript zu installieren.

npm install @azure/communication-identity --save
npm install @azure/communication-network-traversal --save

Mit der Option --save wird die Bibliothek als Abhängigkeit in Ihrer Datei package.json aufgelistet.

Einrichten des App-Frameworks

Über das Projektverzeichnis:

  1. Öffnen einer neuen Textdatei im Code-Editor

  2. Fügen Sie die Direktiven vom Typ require am Anfang der Datei hinzu, um das Azure Communication Identity SDK und das Network Traversal SDK zu verwenden.

  3. Erstellen der Struktur für das Programm, einschließlich einer einfachen Ausnahmebehandlung

    Verwenden Sie zum Einstieg den folgenden Code:

    const { CommunicationIdentityClient } = require("@azure/communication-identity");
    const { CommunicationRelayClient } = require("@azure/communication-network-traversal");;
    
    const main = async () => {
      console.log("Azure Communication Services - Relay Token Quickstart")
    
      // Quickstart code goes here
    };
    
    main().catch((error) => {
      console.log("Encountered and error");
      console.log(error);
    })
    
  4. Speichern Sie die neue Datei im Verzeichnis user-tokens-quickstart als relay-token.js.

Authentifizieren des Clients

Instanziieren Sie einen Kommunikationsidentitätsclient (CommunicationIdentityClient) mit Ihrer Verbindungszeichenfolge. Im folgenden Code wird die Verbindungszeichenfolge für die Ressource aus einer Umgebungsvariablen namens COMMUNICATION_SERVICES_CONNECTION_STRING abgerufen. Informationen zur Verwaltung der Verbindungszeichenfolge Ihrer Ressource.

Fügen Sie der main-Methode folgenden Code hinzu:

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(connectionString);

Erstellen einer Identität

Von Azure Communication Services wird ein einfaches Identitätsverzeichnis gepflegt. Verwenden Sie die Methode createUser, um in dem Verzeichnis einen neuen Eintrag mit einer eindeutigen Id zu erstellen. Speichern Sie die empfangene Identität mit einer Zuordnung zu den Benutzern Ihrer Anwendung. Beispielsweise, indem Sie sie in der Datenbank des Anwendungsservers speichern. Die Identität ist später erforderlich, um Zugriffstoken auszustellen.

let identityResponse = await identityClient.createUser();
console.log(`\nCreated an identity with ID: ${identityResponse.communicationUserId}`);

Austauschen des Benutzerzugriffstokens gegen ein Relaytoken

Rufen Sie den Azure Communication-Tokendienst auf, um das Benutzerzugriffstoken gegen ein TURN-Diensttoken zu tauschen.

    const relayClient = new CommunicationRelayClient(connectionString);
    console.log("Getting relay configuration");

    const config = await relayClient.getRelayConfiguration(identityResponse);
    console.log("RelayConfig", config);

Verwenden des Tokens auf dem Client als ICE-Kandidat

Das Token kann jetzt deserialisiert und als ICE-Kandidat mit WebRTC im Clientbrowser hinzugefügt werden.

var configuration = { iceServers: iceServers };
var peerConnection = new RTCPeerConnection(configuration);

Ausführen des Codes

Navigieren Sie an einer Konsoleneingabeaufforderung zum Verzeichnis mit der Datei issue-token.js, und führen Sie anschließend den folgenden Befehl vom Typ node aus, um die App auszuführen:

node ./relay-token.js

Bereinigen von Ressourcen

Wenn Sie eine Communication Services-Ressource bereinigen und entfernen möchten, können Sie die Ressource oder Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind. Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.