Azure Communication Identity-Clientbibliothek für Java – Version 1.4.11

  • Artikel

Das Identitätspaket wird zum Verwalten von Benutzern und Token für Azure Communication Services verwendet.

Quellcode | Paket (Maven) | API-Referenzdokumentation | Produktdokumentation

Erste Schritte

Voraussetzungen

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der General Availability (GA)-Version der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste 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-identity</artifactId>
  </dependency>
</dependencies>

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

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

Authentifizieren des Clients

Es gibt zwei Arten der Authentifizierung, um das Identity SDK zu verwenden:

Azure Active Directory-Tokenauthentifizierung

Ein DefaultAzureCredential -Objekt muss über die CommunicationIdentityClientBuilder credential()-Funktion an die übergeben werden. Endpunkt und httpClient müssen auch über die Funktionen endpoint() bzw. httpClient() festgelegt werden.

AZURE_CLIENT_SECRET, AZURE_CLIENT_ID und AZURE_TENANT_ID Umgebungsvariablen werden benötigt, um ein DefaultAzureCredential-Objekt zu erstellen.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

AzureKeyCredential-Authentifizierung

Identity verwendet die HMAC-Authentifizierung mit dem Ressourcenzugriffsschlüssel. Der Zugriffsschlüssel kann verwendet werden, um azureKeyCredential zu erstellen und über die CommunicationIdentityClientBuilder credential()-Funktion zur Verfügung zu stellen. Endpunkt und httpClient müssen auch über die Funktionen endpoint() bzw. httpClient() festgelegt werden.

// You can find your endpoint and access key from your resource in the Azure Portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
AzureKeyCredential keyCredential = new AzureKeyCredential("<access-key>");

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .endpoint(endpoint)
    .credential(keyCredential)
    .buildClient();

Verbindungszeichenfolgenauthentifizierung

Alternativ können Sie die gesamte Verbindungszeichenfolge mithilfe der Funktion connectionString() bereitstellen, anstatt den Endpunkt und den Zugriffsschlüssel bereitzustellen.

// You can find your connection string from your resource in the Azure Portal
String connectionString = "<connection_string>";

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

Wichtige Begriffe

CommunicationIdentityClient und CommunicationIdentityAsyncClient stellen die Funktionen zum Verwalten von Benutzern und Benutzertoken bereit.

Beispiele

Erstellen eines neuen Benutzers

Verwenden Sie die createUser Funktion, um einen neuen Benutzer zu erstellen. user.getId() ruft die eindeutige ID des erstellten Benutzers ab.

CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("User id: " + user.getId());

Abrufen eines Tokens für einen vorhandenen Benutzer

Verwenden Sie die getToken Funktion, um ein Token für einen vorhandenen Benutzer abzurufen. Die Funktion übernimmt auch eine Liste von CommunicationTokenScope. Zu den Bereichsoptionen gehören:

  • chat (Chat)
  • voip (Voice over IP)
 // Define a list of communication token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);

AccessToken userToken = communicationIdentityClient.getToken(user, scopes);
System.out.println("User token value: " + userToken.getToken());
System.out.println("Expires at: " + userToken.getExpiresAt());

Es ist auch möglich, ein Kommunikationsidentitäts-Zugriffstoken zu erstellen, indem Sie die Ablaufzeit anpassen. Das Token kann so konfiguriert werden, dass es in nur einer Stunde oder bis zu 24 Stunden abläuft. Die Standardablaufzeit beträgt 24 Stunden.

// Define a list of Communication Identity access token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
// Set custom validity period of the Communication Identity access token within [1,24]
// hours range. If not provided, the default value of 24 hours will be used.
Duration tokenExpiresIn = Duration.ofHours(1);
AccessToken userToken = communicationIdentityClient.getToken(user, scopes, tokenExpiresIn);
System.out.println("User token value: " + userToken.getToken());
System.out.println("Expires at: " + userToken.getExpiresAt());

Erstellen eines neuen Benutzers und Tokens in einer einzelnen Anforderung

Verwenden createUserAndToken Sie der Einfachheit halber, um einen neuen Benutzer zu erstellen und ein Token mit einem Funktionsaufruf auszustellen. Dies wird in eine einzelne Webanforderung übersetzt, anstatt zuerst einen Benutzer zu erstellen und dann ein Token auszugeben.

// Define a list of communication token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);

CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes);
System.out.println("User id: " + result.getUser().getId());
System.out.println("User token value: " + result.getUserToken().getToken());

Hier ist es auch möglich, die Ablaufzeit für das Kommunikationsidentitäts-Zugriffstoken anzugeben. Das Token kann so konfiguriert werden, dass es in nur einer Stunde oder bis zu 24 Stunden abläuft. Die Standardablaufzeit beträgt 24 Stunden.

// Define a list of communication token scopes
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
// Set custom validity period of the Communication Identity access token within [1,24]
// hours range. If not provided, the default value of 24 hours will be used.
Duration tokenExpiresIn = Duration.ofHours(1);
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes, tokenExpiresIn);
System.out.println("User id: " + result.getUser().getId());
System.out.println("User token value: " + result.getUserToken().getToken());

Widerrufen aller Token für einen vorhandenen Benutzer

Verwenden Sie die revokeTokens -Funktion, um alle ausgestellten Token eines Benutzers zu widerrufen.

// revoke tokens issued for the specified user
communicationIdentityClient.revokeTokens(user);

Löschen eines Benutzers

Verwenden Sie die deleteUser Funktion, um einen Benutzer zu löschen.

// delete a previously created user
communicationIdentityClient.deleteUser(user);

Austauschen des Azure AD-Zugriffstokens eines Teams-Benutzers gegen ein Kommunikationsidentitäts-Zugriffstoken

Verwenden Sie die getTokenForTeamsUser Funktion, um ein Azure AD-Zugriffstoken eines Teams-Benutzers gegen ein neues Kommunikationsidentitätszugriffstoken auszutauschen.

String clientId = "<Client ID of an Azure AD application>";
String userObjectId = "<Object ID of an Azure AD user (Teams User)>";
GetTokenForTeamsUserOptions options = new GetTokenForTeamsUserOptions(teamsUserAadToken, clientId, userObjectId);
AccessToken accessToken = communicationIdentityClient.getTokenForTeamsUser(options);
System.out.println("User token value: " + accessToken.getToken());
System.out.println("Expires at: " + accessToken.getExpiresAt());

Problembehandlung

Bei allen Vorgängen des Benutzertokendiensts wird bei Einem Fehler eine Ausnahme ausgelöst.

try {
    CommunicationUserIdentifier user = communicationIdentityClient.createUser();
} catch (RuntimeException ex) {
    System.out.println(ex.getMessage());
}

Nächste Schritte

Sehen Sie sich das Beispielverzeichnis an, um detaillierte Beispiele für die Verwendung dieser Bibliothek zum Verwalten von Identitäten und Token zu erhalten.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Für die meisten Beiträge ist die Zustimmung zu einer Lizenzvereinbarung für Mitwirkende (Contributor License Agreement, CLA) erforderlich, in der Sie erklären, dass Sie dazu berechtigt sind, uns die Rechte für die Nutzung Ihres Beitrags zu erteilen, und dies auch tun.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe