Szybki start: tworzenie tokenów dostępu i zarządzanie nimi

Tokeny dostępu umożliwiają zestawom SDK usług Azure Communication Services uwierzytelnianie bezpośrednio w usługach Azure Communication Services jako konkretnej tożsamości. Jeśli chcesz, aby użytkownicy dołączyli do połączenia lub wątku czatu w aplikacji, musisz utworzyć tokeny dostępu.

W tym przewodniku Szybki start dowiesz się, jak używać zestawów SDK usług Azure Communication Services do tworzenia tożsamości i zarządzania tokenami dostępu. W przypadku przypadków użycia w środowisku produkcyjnym zalecamy generowanie tokenów dostępu w usłudze po stronie serwera.

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Aktywny zasób usług komunikacyjnych i parametry połączenia. Utwórz zasób usług komunikacyjnych.
• Zainstaluj interfejs wiersza polecenia platformy Azure.

Konfigurowanie

Dodawanie rozszerzenia

Dodaj rozszerzenie Azure Communication Services dla interfejsu wiersza polecenia platformy az extension Azure przy użyciu polecenia .

az extension add --name communication

Logowanie do interfejsu wiersza polecenia platformy Azure

Musisz zalogować się do interfejsu wiersza polecenia platformy Azure. Możesz zalogować się, uruchamiając polecenie z poziomu terminalu az login i podając swoje poświadczenia.

(Opcjonalnie) Używanie operacji tożsamości interfejsu wiersza polecenia platformy Azure bez przekazywania parametry połączenia

Zmienną AZURE_COMMUNICATION_CONNECTION_STRING środowiskową można skonfigurować tak, aby korzystała z operacji tożsamości interfejsu wiersza polecenia platformy Azure bez konieczności przekazywania --connection_string parametry połączenia. Aby skonfigurować zmienną środowiskową, otwórz okno konsoli i wybierz system operacyjny z poniższych kart. Zastąp <yourConnectionString> element rzeczywistym parametry połączenia.

Windows

Otwórz okno konsoli i wprowadź następujące polecenie:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Po dodaniu zmiennej środowiskowej być może trzeba będzie ponownie uruchomić działające programy, które muszą odczytywać zmienną środowiskową, w tym okno konsoli. Jeśli na przykład używasz programu Visual Studio jako edytora, uruchom ponownie program Visual Studio przed uruchomieniem przykładu.

macOS

.zshrcEdytuj zmienną środowiskową i dodaj zmienną środowiskową:

export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"

Po dodaniu zmiennej środowiskowej uruchom polecenie source ~/.zshrc z okna konsoli, aby zmiany zostały uwzględnione. Jeśli zmienna środowiskowa została utworzona przy otwartym środowisku IDE, może być konieczne zamknięcie i ponowne otwarcie edytora, środowiska IDE lub powłoki w celu uzyskania dostępu do zmiennej.

Linux

.bash_profileEdytuj zmienną środowiskową i dodaj zmienną środowiskową:

export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"

Po dodaniu zmiennej środowiskowej uruchom polecenie source ~/.bash_profile z okna konsoli, aby zmiany zostały uwzględnione. Jeśli zmienna środowiskowa została utworzona przy otwartym środowisku IDE, może być konieczne zamknięcie i ponowne otwarcie edytora, środowiska IDE lub powłoki w celu uzyskania dostępu do zmiennej.

Przechowywanie tokenu dostępu w zmiennej środowiskowej

Aby skonfigurować zmienną środowiskową, otwórz okno konsoli i wybierz system operacyjny z poniższych kart. Zastąp <yourAccessToken> element rzeczywistym tokenem dostępu.

Windows

Otwórz okno konsoli i wprowadź następujące polecenie:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Po dodaniu zmiennej środowiskowej być może trzeba będzie ponownie uruchomić działające programy, które muszą odczytywać zmienną środowiskową, w tym okno konsoli. Jeśli na przykład używasz programu Visual Studio jako edytora, uruchom ponownie program Visual Studio przed uruchomieniem przykładu.

macOS

.zshrcEdytuj zmienną środowiskową i dodaj zmienną środowiskową:

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Po dodaniu zmiennej środowiskowej uruchom polecenie source ~/.zshrc z okna konsoli, aby zmiany zostały uwzględnione. Jeśli zmienna środowiskowa została utworzona przy otwartym środowisku IDE, może być konieczne zamknięcie i ponowne otwarcie edytora, środowiska IDE lub powłoki w celu uzyskania dostępu do zmiennej.

Linux

.bash_profileEdytuj zmienną środowiskową i dodaj zmienną środowiskową:

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Po dodaniu zmiennej środowiskowej uruchom polecenie source ~/.bash_profile z okna konsoli, aby zmiany zostały uwzględnione. Jeśli zmienna środowiskowa została utworzona przy otwartym środowisku IDE, może być konieczne zamknięcie i ponowne otwarcie edytora, środowiska IDE lub powłoki w celu uzyskania dostępu do zmiennej.

Operacje

Tworzenie tożsamości

Aby utworzyć tokeny dostępu, potrzebna jest tożsamość. W tym celu usługi Azure Communication Services utrzymują uproszczony katalog tożsamości. Użyj polecenia , user create aby utworzyć nowy wpis w katalogu z unikatowym Idelementem . Tożsamość jest później wymagana do wystawiania tokenów dostępu.

az communication identity user create --connection-string "<yourConnectionString>"

• Zastąp <yourConnectionString> element parametry połączenia.

Tworzenie tożsamości i wystawianie tokenu dostępu w tym samym żądaniu

Uruchom następujące polecenie, aby utworzyć tożsamość usług komunikacyjnych i w tym samym czasie wydać token dostępu. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w temacie Uwierzytelnianie w usługach Azure Communication Services.

az communication identity token issue --scope chat --connection-string "<yourConnectionString>"

Zastąp ten kod:

• Zastąp <yourConnectionString> element parametry połączenia.

Problem z tokenem dostępu

Uruchom następujące polecenie, aby wydać token dostępu dla tożsamości usług komunikacyjnych. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w temacie Uwierzytelnianie w usługach Azure Communication Services.

az communication identity token issue --scope chat --user "<userId>" --connection-string "<yourConnectionString>"

Zastąp ten kod:

• Zastąp <yourConnectionString> element parametry połączenia.
• Zastąp <userId> ciąg identyfikatorem userId.

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Takie działanie może spowodować zakłócenia środowiska użytkowników aplikacji. Właściwość expires_on odpowiedzi wskazuje okres istnienia tokenu dostępu.

Wystawianie tokenu dostępu z wieloma zakresami

Uruchom następujące polecenie, aby wydać token dostępu z wieloma zakresami tożsamości usług komunikacyjnych. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w modelu tożsamości.

az communication identity token issue --scope chat voip --user "<userId>" --connection-string "<yourConnectionString>"

Zastąp ten kod:

• Zastąp <yourConnectionString> element parametry połączenia.
• Zastąp <userId> ciąg identyfikatorem userId.

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Takie działanie może spowodować zakłócenia środowiska użytkowników aplikacji. Właściwość expires_on odpowiedzi wskazuje okres istnienia tokenu dostępu.

Exchange a Microsoft Entra access token of the Teams User for a Communication Identity access token (Wymiana tokenu dostępu do tożsamości komunikacji w usłudze Teams)

token get-for-teams-user Użyj polecenia , aby wydać token dostępu dla użytkownika usługi Teams, który może być używany z zestawami SDK usług Azure Communication Services.

az communication identity token get-for-teams-user --aad-token "<yourAadToken>" --client "<yourAadApplication>" --aad-user "<yourAadUser>" --connection-string "<yourConnectionString>"

Zastąp ten kod:

• Zastąp <yourConnectionString> element parametry połączenia.
• Zastąp <yourAadUser> ciąg identyfikatorem userId firmy Microsoft.
• Zastąp <yourAadApplication> ciąg identyfikatorem aplikacji Entra firmy Microsoft.
• Zastąp <yourAadToken> ciąg swoim tokenem dostępu firmy Microsoft Entra.

Odwoływanie tokenów dostępu

Czasami może być konieczne jawne odwołanie tokenu dostępu. Można to zrobić na przykład wtedy, gdy użytkownicy aplikacji zmienią hasło, którego używają do uwierzytelniania w usłudze. Polecenie token revoke unieważnia wszystkie aktywne tokeny dostępu, które zostały wystawione dla tożsamości.

az communication identity token revoke --user "<userId>" --connection-string "<yourConnectionString>"

Zastąp ten kod:

• Zastąp <yourConnectionString> element parametry połączenia.
• Zastąp <userId> ciąg identyfikatorem userId.

Usuwanie tożsamości

Usunięcie tożsamości powoduje odwołanie wszystkich aktywnych tokenów dostępu i uniemożliwienie dalszego wystawiania tokenów dostępu dla tożsamości. Spowoduje to również usunięcie całej utrwalonej zawartości skojarzonej z tożsamością.

az communication identity user delete --user "<userId>" --connection-string "<yourConnectionString>"

Zastąp ten kod:

• Zastąp <yourConnectionString> element parametry połączenia.
• Zastąp <userId> ciąg identyfikatorem userId.

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Najnowsza wersja zestawu .NET Core SDK dla systemu operacyjnego.
• Aktywny zasób usług komunikacyjnych i parametry połączenia. Utwórz zasób usług komunikacyjnych.

Kod końcowy

Znajdź sfinalizowany kod dla tego przewodnika Szybki start w witrynie GitHub.

Konfigurowanie środowiska

Tworzenie nowej aplikacji w języku C#

W oknie wiersza polecenia, takim jak cmd, PowerShell lub Bash, uruchom dotnet new polecenie , aby utworzyć nową aplikację konsolową o nazwie AccessTokensQuickstart. To polecenie tworzy prosty projekt języka C# "Hello World" z pojedynczym plikiem źródłowym, Program.cs.

dotnet new console -o AccessTokensQuickstart

Zmień katalog na nowo utworzony folder aplikacji i użyj dotnet build polecenia , aby skompilować aplikację.

cd AccessTokensQuickstart
dotnet build

Powinny zostać wyświetlone proste dane wyjściowe "Hello World". Jeśli tak jest, konfiguracja działa poprawnie i możesz rozpocząć pisanie kodu specyficznego dla usług Azure Communication Services.

Instalowanie pakietu

Mimo że nadal znajdujesz się w katalogu aplikacji, zainstaluj bibliotekę tożsamości usług Azure Communication Services dla pakietu .NET przy użyciu dotnet add package polecenia .

dotnet add package Azure.Communication.Identity

Konfigurowanie struktury aplikacji

W katalogu projektu wykonaj następujące czynności:

1. Otwórz plik Program.cs w edytorze tekstów.
2. Dodaj dyrektywę using , aby uwzględnić Azure.Communication.Identity przestrzeń nazw.
3. Zaktualizuj deklarację Main metody w celu obsługi kodu asynchronicznego.

Aby rozpocząć, uruchom następujący kod:

using System;
using Azure;
using Azure.Core;
using Azure.Communication.Identity;

namespace AccessTokensQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Access Tokens Quickstart");

            // Quickstart code goes here
        }
    }
}

Uwierzytelnianie użytkownika

Zainicjuj CommunicationIdentityClient parametry połączenia. Poniższy kod, który zostanie dodany do Main metody, pobiera parametry połączenia dla zasobu ze zmiennej środowiskowej o nazwie COMMUNICATION_SERVICES_CONNECTION_STRING.

Aby uzyskać więcej informacji, zobacz sekcję "Przechowywanie parametry połączenia" w temacie Tworzenie zasobów usług komunikacyjnych i zarządzanie nimi.

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

Alternatywnie możesz oddzielić punkt końcowy i klucz dostępu, uruchamiając następujący kod:

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
string endpoint = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ENDPOINT");
string accessKey = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ACCESSKEY");
var client = new CommunicationIdentityClient(new Uri(endpoint), new AzureKeyCredential(accessKey));

Jeśli masz już skonfigurowaną aplikację Firmy Microsoft Entra, możesz uwierzytelnić się przy użyciu identyfikatora Entra firmy Microsoft.

TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);

Tworzenie tożsamości

Aby utworzyć tokeny dostępu, potrzebna jest tożsamość. W tym celu usługi Azure Communication Services utrzymują uproszczony katalog tożsamości. createUser Użyj metody , aby utworzyć nowy wpis w katalogu z unikatowym Idelementem . Tożsamość jest później wymagana do wystawiania tokenów dostępu.

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

Zapisz odebraną tożsamość z mapowaniem na użytkowników aplikacji (na przykład przechowuj ją w bazie danych serwera aplikacji).

Wystawianie tokenu dostępu

Po utworzeniu tożsamości usług komunikacyjnych użyj GetToken metody w celu wystawienia tokenu dostępu. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w modelu tożsamości. Możesz również utworzyć nowe wystąpienie communicationUser na podstawie ciągu reprezentującego tożsamość usługi Azure Communication Service.

// Issue an access token with a validity of 24 hours and the "voip" scope for an identity
var tokenResponse = await client.GetTokenAsync(identity, scopes: new [] { CommunicationTokenScope.VoIP });

// Get the token from the response
var token =  tokenResponse.Value.Token;
var expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Takie działanie może spowodować zakłócenia środowiska użytkowników aplikacji. Właściwość expiresOn wskazuje okres istnienia tokenu dostępu.

Ustawianie niestandardowego czasu wygaśnięcia tokenu

Domyślny czas wygaśnięcia tokenu wynosi 24 godziny, ale można go skonfigurować, podając wartość z zakresu od godziny do 24 godzin do opcjonalnego parametru tokenExpiresIn. Podczas żądania nowego tokenu zaleca się określenie oczekiwanej typowej długości sesji komunikacji dla czasu wygaśnięcia tokenu.

// Issue an access token with a validity of an hour and the "voip" scope for an identity 
TimeSpan tokenExpiresIn = TimeSpan.FromHours(1);
CommunicationTokenScope[] scopes = new[] { CommunicationTokenScope.VoIP };
var tokenResponse = await client.GetTokenAsync(identity, scopes, tokenExpiresIn);

Tworzenie tożsamości i wystawianie tokenu w tym samym żądaniu

Możesz użyć CreateUserAndTokenAsync metody , aby utworzyć tożsamość usług komunikacyjnych i w tym samym czasie wydać token dostępu. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w temacie Uwierzytelnianie w usługach Azure Communication Services.

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
var identityAndTokenResponse = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.VoIP });

// Retrieve the identity, token, and expiration date from the response
var identity = identityAndTokenResponse.Value.User;
var token = identityAndTokenResponse.Value.AccessToken.Token;
var expiresOn = identityAndTokenResponse.Value.AccessToken.ExpiresOn;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Odświeżanie tokenu dostępu

Aby odświeżyć token dostępu, przekaż wystąpienie CommunicationUserIdentifier obiektu do GetTokenAsyncobiektu . Jeśli ta Id funkcja jest przechowywana i musisz utworzyć nowy CommunicationUserIdentifierelement , możesz to zrobić, przekazując dane przechowywane Id do konstruktora CommunicationUserIdentifier w następujący sposób:

var identityToRefresh = new CommunicationUserIdentifier(identity.Id);
var tokenResponse = await client.GetTokenAsync(identityToRefresh, scopes: new [] { CommunicationTokenScope.VoIP });

Odwoływanie tokenów dostępu

Czasami może być konieczne jawne odwołanie tokenu dostępu. Można to zrobić na przykład wtedy, gdy użytkownicy aplikacji zmienią hasło, którego używają do uwierzytelniania w usłudze. Metoda RevokeTokensAsync unieważnia wszystkie aktywne tokeny dostępu, które zostały wystawione dla tożsamości.

await client.RevokeTokensAsync(identity);
Console.WriteLine($"\nSuccessfully revoked all access tokens for identity with ID: {identity.Id}");

Usuwanie tożsamości

Usunięcie tożsamości powoduje odwołanie wszystkich aktywnych tokenów dostępu i uniemożliwienie dalszego wystawiania tokenów dostępu dla tożsamości. Spowoduje to również usunięcie całej utrwalonej zawartości skojarzonej z tożsamością.

await client.DeleteUserAsync(identity);
Console.WriteLine($"\nDeleted the identity with ID: {identity.Id}");

Uruchamianie kodu

Po zakończeniu tworzenia tokenu dostępu możesz uruchomić aplikację z katalogu aplikacji przy użyciu dotnet run polecenia .

dotnet run

Dane wyjściowe aplikacji opisują każdą ukończoną akcję:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 10/11/2022 7:34:29 AM +00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 10/11/2022 7:34:29 AM +00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Node.js wersji LTS Active LTS i Maintenance LTS (zalecane wersje 8.11.1 i 10.14.1).
• Aktywny zasób usług komunikacyjnych i parametry połączenia. Utwórz zasób usług komunikacyjnych.

Kod końcowy

Znajdź sfinalizowany kod dla tego przewodnika Szybki start w witrynie GitHub.

Konfigurowanie środowiska

Tworzenie nowej aplikacji Node.js

W oknie terminalu lub wiersza polecenia utwórz nowy katalog dla aplikacji, a następnie otwórz go.

mkdir access-tokens-quickstart && cd access-tokens-quickstart

Uruchom polecenie npm init -y , aby utworzyć plik package.json z ustawieniami domyślnymi.

npm init -y

Instalowanie pakietu

Użyj polecenia , npm install aby zainstalować zestaw SDK tożsamości usług Azure Communication Services dla języka JavaScript.

npm install @azure/communication-identity@latest --save

Opcja --save wyświetla bibliotekę jako zależność w pliku package.json .

Konfigurowanie struktury aplikacji

1. Utwórz plik o nazwie issue-access-token.js w katalogu projektu i dodaj następujący kod:

   const { CommunicationIdentityClient } = require('@azure/communication-identity');
   
   const main = async () => {
     console.log("Azure Communication Services - Access Tokens Quickstart")
   
     // Quickstart code goes here
   };
   
   main().catch((error) => {
     console.log("Encountered an error");
     console.log(error);
   })
   

Uwierzytelnianie użytkownika

CommunicationIdentityClient Utwórz wystąpienie przy użyciu parametry połączenia. Poniższy kod, który zostanie dodany do Main metody, pobiera parametry połączenia dla zasobu ze zmiennej środowiskowej o nazwie COMMUNICATION_SERVICES_CONNECTION_STRING.

Aby uzyskać więcej informacji, zobacz sekcję "Przechowywanie parametry połączenia" w temacie Tworzenie zasobów usług komunikacyjnych i zarządzanie nimi.

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

Alternatywnie możesz oddzielić punkt końcowy i klucz dostępu, uruchamiając następujący kod:

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const accessKey = process.env["COMMUNICATION_SERVICES_ACCESSKEY"];

// Create the credential
const tokenCredential = new AzureKeyCredential(accessKey);

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential)

Jeśli masz już skonfigurowaną aplikację Firmy Microsoft Entra, możesz uwierzytelnić się przy użyciu identyfikatora Entra firmy Microsoft.

const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const tokenCredential = new DefaultAzureCredential();
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential);

Tworzenie tożsamości

Aby utworzyć tokeny dostępu, potrzebna jest tożsamość. W tym celu usługi Azure Communication Services utrzymują uproszczony katalog tożsamości. createUser Użyj metody , aby utworzyć nowy wpis w katalogu z unikatowym Idelementem . Tożsamość jest później wymagana do wystawiania tokenów dostępu.

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

Zapisz odebraną tożsamość z mapowaniem na użytkowników aplikacji (na przykład przechowuj ją w bazie danych serwera aplikacji).

Wystawianie tokenu dostępu

getToken Użyj metody , aby wydać token dostępu dla tożsamości usług komunikacyjnych. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w modelu tożsamości. Możesz również utworzyć nowe wystąpienie communicationUser obiektu na podstawie ciągu reprezentującego tożsamość usługi Azure Communication Service.

// Issue an access token with a validity of 24 hours and the "voip" scope for an identity
let tokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

// Get the token and its expiration date from the response
const { token, expiresOn } = tokenResponse;
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Takie działanie może spowodować zakłócenia środowiska użytkowników aplikacji. Właściwość expiresOn wskazuje okres istnienia tokenu dostępu.

Ustawianie niestandardowego czasu wygaśnięcia tokenu

Domyślny czas wygaśnięcia tokenu to 24 godziny (1440 minut), ale można go skonfigurować, podając wartość z zakresu od 60 minut do 1440 minut do opcjonalnego parametru tokenExpiresInMinutes. Podczas żądania nowego tokenu zaleca się określenie oczekiwanej typowej długości sesji komunikacji dla czasu wygaśnięcia tokenu.

// Issue an access token with a validity of an hour and the "voip" scope for an identity
const tokenOptions: GetTokenOptions = { tokenExpiresInMinutes: 60 };
let tokenResponse = await identityClient.getToken
(identityResponse, ["voip"], tokenOptions);

Tworzenie tożsamości i wystawianie tokenu w jednym wywołaniu metody

Możesz użyć createUserAndToken metody , aby utworzyć tożsamość usług komunikacyjnych i w tym samym czasie wydać token dostępu. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Ponownie utworzysz go z zakresem voip .

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
let identityTokenResponse = await identityClient.createUserAndToken(["voip"]);

// Get the token, its expiration date, and the user from the response
const { token, expiresOn, user } = identityTokenResponse;
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Odświeżanie tokenu dostępu

Po wygaśnięciu tokenów należy je okresowo odświeżyć. Odświeżanie jest łatwe po prostu wywołanie getToken ponownie przy użyciu tej samej tożsamości, która została użyta do wystawiania tokenów. Należy również podać scopes odświeżone tokeny.

// Value of identityResponse represents the Azure Communication Services identity stored during identity creation and then used to issue the tokens being refreshed
let refreshedTokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

Odwoływanie tokenów dostępu

Czasami może być konieczne odwołanie tokenu dostępu. Można to zrobić na przykład wtedy, gdy użytkownicy aplikacji zmienią hasło, którego używają do uwierzytelniania w usłudze. Metoda revokeTokens unieważnia wszystkie aktywne tokeny dostępu, które zostały wystawione dla tożsamości.

await identityClient.revokeTokens(identityResponse);

console.log(`\nSuccessfully revoked all access tokens for identity with ID: ${identityResponse.communicationUserId}`);

Usuwanie tożsamości

Usunięcie tożsamości powoduje odwołanie wszystkich aktywnych tokenów dostępu i uniemożliwienie dalszego wystawiania tokenów dostępu dla tożsamości. Spowoduje to również usunięcie całej utrwalonej zawartości skojarzonej z tożsamością.

await identityClient.deleteUser(identityResponse);

console.log(`\nDeleted the identity with ID: ${identityResponse.communicationUserId}`);

Uruchamianie kodu

W wierszu polecenia konsoli przejdź do katalogu zawierającego plik issue-access-token.js , a następnie wykonaj następujące node polecenie, aby uruchomić aplikację:

node ./issue-access-token.js

Dane wyjściowe aplikacji opisują każdą ukończoną akcję:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Środowisko Python w wersji 3.8 lub nowszej.
• Aktywny zasób usług komunikacyjnych i parametry połączenia. Utwórz zasób usług komunikacyjnych.

Kod końcowy

Znajdź sfinalizowany kod dla tego przewodnika Szybki start w witrynie GitHub.

Konfigurowanie środowiska

Tworzenie nowej aplikacji w języku Python

1. W oknie terminalu lub wiersza polecenia utwórz nowy katalog dla aplikacji, a następnie otwórz go.

   mkdir access-tokens-quickstart && cd access-tokens-quickstart
   

2. Użyj edytora tekstów, aby utworzyć plik o nazwie issue-access-tokens.py w katalogu głównym projektu i dodać strukturę programu, w tym podstawową obsługę wyjątków. Do tego pliku w kolejnych sekcjach dodasz cały kod źródłowy tego przewodnika Szybki start.

   import os
   from datetime import timedelta
   from azure.communication.identity import CommunicationIdentityClient, CommunicationUserIdentifier
   
   try:
      print("Azure Communication Services - Access Tokens Quickstart")
      # Quickstart code goes here
   except Exception as ex:
      print("Exception:")
      print(ex)
   

Instalowanie pakietu

Mimo że nadal znajdujesz się w katalogu aplikacji, zainstaluj pakiet Azure Communication Services Identity SDK dla języka Python przy użyciu pip install polecenia .

pip install azure-communication-identity

Uwierzytelnianie użytkownika

Utwórz wystąpienie za CommunicationIdentityClient pomocą parametry połączenia. Poniższy kod, który zostanie dodany do try bloku, pobiera parametry połączenia dla zasobu ze zmiennej środowiskowej o nazwie COMMUNICATION_SERVICES_CONNECTION_STRING.

Aby uzyskać więcej informacji, zobacz sekcję "Przechowywanie parametry połączenia" w temacie Tworzenie zasobów usług komunikacyjnych i zarządzanie nimi.

# This code demonstrates how to retrieve your connection string
# from an environment variable.
connection_string = os.environ["COMMUNICATION_SERVICES_CONNECTION_STRING"]

# Instantiate the identity client
client = CommunicationIdentityClient.from_connection_string(connection_string)

Alternatywnie, jeśli masz już skonfigurowaną aplikację Firmy Microsoft Entra, możesz uwierzytelnić się przy użyciu identyfikatora Entra firmy Microsoft.

endpoint = os.environ["COMMUNICATION_SERVICES_ENDPOINT"]
client = CommunicationIdentityClient(endpoint, DefaultAzureCredential())

Tworzenie tożsamości

Aby utworzyć tokeny dostępu, potrzebna jest tożsamość. W tym celu usługi Azure Communication Services utrzymują uproszczony katalog tożsamości. create_user Użyj metody , aby utworzyć nowy wpis w katalogu z unikatowym Idelementem . Tożsamość jest później wymagana do wystawiania tokenów dostępu.

identity = client.create_user()
print("\nCreated an identity with ID: " + identity.properties['id'])

Zapisz odebraną tożsamość z mapowaniem na użytkowników aplikacji (na przykład przechowuj ją w bazie danych serwera aplikacji).

Wystawianie tokenu dostępu

get_token Użyj metody , aby wydać token dostępu dla tożsamości usług komunikacyjnych. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w modelu tożsamości. Możesz również utworzyć nowe wystąpienie parametru CommunicationUserIdentifier na podstawie ciągu reprezentacji tożsamości usługi Azure Communication Service.

# Issue an access token with a validity of 24 hours and the "voip" scope for an identity
token_result = client.get_token(identity, ["voip"])
print("\nIssued an access token with 'voip' scope that expires at " + token_result.expires_on + ":")
print(token_result.token)

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Takie działanie może spowodować zakłócenia środowiska użytkowników aplikacji. Właściwość expires_on odpowiedzi wskazuje okres istnienia tokenu dostępu.

Ustawianie niestandardowego czasu wygaśnięcia tokenu

Domyślny czas wygaśnięcia tokenu wynosi 24 godziny, ale można go skonfigurować, podając wartość z zakresu od godziny do 24 godzin do opcjonalnego parametru token_expires_in. Podczas żądania nowego tokenu zaleca się określenie oczekiwanej typowej długości sesji komunikacji dla czasu wygaśnięcia tokenu.

# Issue an access token with a validity of an hour and the "voip" scope for an identity
token_expires_in = timedelta(hours=1)
token_result = client.get_token(identity, ["voip"], token_expires_in=token_expires_in)

Tworzenie tożsamości i wystawianie tokenu dostępu w tym samym żądaniu

Możesz użyć create_user_and_token metody , aby utworzyć tożsamość usług komunikacyjnych i w tym samym czasie wydać token dostępu. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w temacie Uwierzytelnianie w usługach Azure Communication Services.

# Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
identity_token_result = client.create_user_and_token(["voip"])

# Get the token details from the response
identity = identity_token_result[0]
token = identity_token_result[1].token
expires_on = identity_token_result[1].expires_on
print("\nCreated an identity with ID: " + identity.properties['id'])
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token)

Odświeżanie tokenu dostępu

Aby odświeżyć token dostępu, użyj CommunicationUserIdentifier obiektu , aby ponownie zainicjować token, przekazując istniejącą tożsamość:

# The existingIdentity value represents the Communication Services identity that's stored during identity creation
identity = CommunicationUserIdentifier(existingIdentity)
token_result = client.get_token(identity, ["voip"])

Odwoływanie tokenów dostępu

Czasami może być konieczne jawne odwołanie tokenu dostępu. Można to zrobić na przykład wtedy, gdy użytkownicy aplikacji zmienią hasło, którego używają do uwierzytelniania w usłudze. Metoda revoke_tokens unieważnia wszystkie aktywne tokeny dostępu, które zostały wystawione dla tożsamości.

client.revoke_tokens(identity)
print("\nSuccessfully revoked all access tokens for identity with ID: " + identity.properties['id'])

Usuwanie tożsamości

Usunięcie tożsamości powoduje odwołanie wszystkich aktywnych tokenów dostępu i uniemożliwienie dalszego wystawiania tokenów dostępu dla tożsamości. Spowoduje to również usunięcie całej utrwalonej zawartości skojarzonej z tożsamością.

client.delete_user(identity)
print("\nDeleted the identity with ID: " + identity.properties['id'])

Uruchamianie kodu

W wierszu polecenia konsoli przejdź do katalogu zawierającego plik issue-access-tokens.py , a następnie wykonaj następujące python polecenie, aby uruchomić aplikację.

python ./issue-access-tokens.py

Dane wyjściowe aplikacji opisują każdą ukończoną akcję:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Zestaw Java Development Kit (JDK) w wersji 8 lub nowszej.
• Apache Maven.
• Aktywny zasób usług komunikacyjnych i parametry połączenia. Utwórz zasób usług komunikacyjnych.

Kod końcowy

Znajdź sfinalizowany kod dla tego przewodnika Szybki start w witrynie GitHub.

Konfigurowanie środowiska

Tworzenie nowej aplikacji Java

W oknie terminalu lub wiersza polecenia przejdź do katalogu, w którym chcesz utworzyć aplikację Java. Aby wygenerować projekt Java na podstawie szablonu maven-archetype-quickstart, uruchom następujący kod:

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

Zauważysz, że generate zadanie tworzy katalog o takiej samej nazwie jak artifactId. W tym katalogu katalog src/main/java zawiera kod źródłowy projektu, katalog src/test/java zawiera źródło testowe, a plik pom.xml jest projektem Project Object Model lub POM. Ten plik jest używany dla parametrów konfiguracji projektu.

Instalowanie pakietów usług Komunikacyjnych

Otwórz plik pom.xml w edytorze tekstów. Dodaj następujący element zależności do grupy zależności:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
    <version>[1.4.0,)</version>
</dependency>

Ten kod instruuje narzędzie Maven, aby zainstalować zestaw SDK tożsamości usług komunikacyjnych, który będzie używany później.

Konfigurowanie struktury aplikacji

W katalogu projektu wykonaj następujące czynności:

1. Przejdź do katalogu /src/main/java/com/communication/quickstart .
2. Otwórz plik App.java w edytorze.
3. Zastąp instrukcję System.out.println("Hello world!"); .
4. Dodaj import dyrektywy.

Użyj następującego kodu, aby rozpocząć:

package com.communication.quickstart;

import com.azure.communication.common.*;
import com.azure.communication.identity.*;
import com.azure.communication.identity.models.*;
import com.azure.core.credential.*;

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 - Access Tokens Quickstart");
        // Quickstart code goes here
    }
}

Uwierzytelnianie użytkownika

CommunicationIdentityClient Utwórz wystąpienie elementu przy użyciu klucza dostępu zasobu i punktu końcowego. Aby uzyskać więcej informacji, zobacz sekcję "Przechowywanie parametry połączenia" w temacie Tworzenie zasobów usług komunikacyjnych i zarządzanie nimi.

Ponadto można zainicjować klienta przy użyciu dowolnego niestandardowego klienta HTTP, który implementuje com.azure.core.http.HttpClient interfejs.

W pliku App.java dodaj następujący kod do main metody :

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

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

Zamiast dostarczać punkt końcowy i klucz dostępu, możesz podać całą parametry połączenia przy użyciu connectionString() metody .

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

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

Jeśli masz już skonfigurowaną aplikację Firmy Microsoft Entra, możesz uwierzytelnić się przy użyciu identyfikatora Entra firmy Microsoft.

String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
TokenCredential credential = new DefaultAzureCredentialBuilder().build();

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

Tworzenie tożsamości

Aby utworzyć tokeny dostępu, potrzebna jest tożsamość. W tym celu usługi Azure Communication Services utrzymują uproszczony katalog tożsamości. createUser Użyj metody , aby utworzyć nowy wpis w katalogu z unikatowym Idelementem .

CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("\nCreated an identity with ID: " + user.getId());

Utworzona tożsamość jest później wymagana do wystawiania tokenów dostępu. Zapisz odebraną tożsamość z mapowaniem na użytkowników aplikacji (na przykład przechowuj ją w bazie danych serwera aplikacji).

Wystawianie tokenu dostępu

getToken Użyj metody , aby wydać token dostępu dla tożsamości usług komunikacyjnych. Parametr scopes definiuje zestaw uprawnień i ról tokenu dostępu. Aby uzyskać więcej informacji, zobacz listę obsługiwanych akcji w modelu tożsamości.

W poniższym kodzie użyj zmiennej użytkownika utworzonej w poprzednim kroku, aby uzyskać token.

// Issue an access token with a validity of 24 hours and the "voip" scope for a user identity
List<CommunicationTokenScope> scopes = new ArrayList<>(Arrays.asList(CommunicationTokenScope.VOIP));
AccessToken accessToken = communicationIdentityClient.getToken(user, scopes);
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'voip' scope that expires at: " + expiresAt + ": " + token);

Tokeny dostępu to krótkotrwałe poświadczenia, które muszą zostać ponownie wystawione. Takie działanie może spowodować zakłócenia środowiska użytkowników aplikacji. Właściwość expiresAt wskazuje okres istnienia tokenu dostępu.

Ustawianie niestandardowego czasu wygaśnięcia tokenu

Domyślny czas wygaśnięcia tokenu wynosi 24 godziny, ale można go skonfigurować, podając wartość z zakresu od godziny do 24 godzin do opcjonalnego parametru tokenExpiresIn. Podczas żądania nowego tokenu zaleca się określenie oczekiwanej typowej długości sesji komunikacji dla czasu wygaśnięcia tokenu.

// Issue an access token with a validity of an hour and the "voip" scope for a user identity
List<CommunicationTokenScope> scopes = new ArrayList<>(Arrays.asList(CommunicationTokenScope.VOIP));
Duration tokenExpiresIn = Duration.ofHours(1);
AccessToken accessToken = communicationIdentityClient.getToken(user, scopes, tokenExpiresIn);

Tworzenie tożsamości i wystawianie tokenu w jednym żądaniu

Alternatywnie możesz użyć metody "createUserAndToken", aby utworzyć nowy wpis w katalogu z unikatowym Id i wystawiać token dostępu w tym samym czasie.

//Create an identity and issue token with a validity of 24 hours in one call
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes);
CommunicationUserIdentifier user = result.getUser();
System.out.println("\nCreated a user identity with ID: " + user.getId());
AccessToken accessToken = result.getUserToken();
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'chat' scope that expires at: " + expiresAt + ": " + token);

Odświeżanie tokenu dostępu

Aby odświeżyć token dostępu, użyj CommunicationUserIdentifier obiektu , aby go ponownie zainicjować:

// existingIdentity represents the Communication Services identity that's stored during identity creation
CommunicationUserIdentifier identity = new CommunicationUserIdentifier(existingIdentity.getId());
AccessToken response = communicationIdentityClient.getToken(identity, scopes);

Odwoływanie tokenu dostępu

Czasami może być konieczne jawne odwołanie tokenu dostępu. Można to zrobić na przykład wtedy, gdy użytkownicy aplikacji zmienią hasło, którego używają do uwierzytelniania w usłudze. Metoda revokeTokens unieważnia wszystkie aktywne tokeny dostępu dla określonego użytkownika. W poniższym kodzie możesz użyć wcześniej utworzonego użytkownika.

communicationIdentityClient.revokeTokens(user);
System.out.println("\nSuccessfully revoked all access tokens for user identity with ID: " + user.getId());

Usuwanie tożsamości

Usunięcie tożsamości powoduje odwołanie wszystkich aktywnych tokenów dostępu i uniemożliwienie dalszego wystawiania tokenów dostępu dla tożsamości. Spowoduje to również usunięcie całej utrwalonej zawartości skojarzonej z tożsamością.

communicationIdentityClient.deleteUser(user);
System.out.println("\nDeleted the user identity with ID: " + user.getId());

Uruchamianie kodu

Przejdź do katalogu zawierającego plik pom.xml , a następnie skompiluj projekt przy użyciu następującego mvn polecenia:

mvn compile

Następnie skompiluj pakiet:

mvn package

Uruchom następujące mvn polecenie, aby wykonać aplikację:

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

Dane wyjściowe aplikacji opisują każdą ukończoną akcję:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.902864800Z:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'chat' scope that expires at 2022-10-11T07:34:29.902864800Z:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Wymagania wstępne

• Zasób usług Azure Communication Services

Tworzenie tokenów dostępu

W witrynie Azure Portal przejdź do bloku Tożsamości i tokeny dostępu użytkowników w zasobie usług Komunikacyjnych.

Wybierz zakres tokenów dostępu. Możesz wybrać brak, jedną lub wiele. Kliknij pozycję Generate (Generuj).

Zobaczysz tożsamość i wygenerowany odpowiedni token dostępu użytkownika. Możesz skopiować te ciągi i użyć ich w przykładowych aplikacjach i innych scenariuszach testowania.

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją lub bezpłatne utworzenie konta platformy Azure.

• Aktywny zasób usług Azure Communication Services lub utwórz zasób usług komunikacyjnych.

• Aktywny zasób usługi Azure Logic Apps (aplikacja logiki) lub utwórz przepływ pracy aplikacji logiki Zużycie z wyzwalaczem, którego chcesz użyć. Obecnie łącznik tożsamości usług Azure Communication Services udostępnia tylko akcje, więc aplikacja logiki wymaga co najmniej wyzwalacza.

Utwórz użytkownika

Dodaj nowy krok w przepływie pracy przy użyciu łącznika tożsamości usług Azure Communication Services. Wykonaj następujące kroki w usłudze Power Automate z otwartym przepływem usługi Power Automate w trybie edycji.

1. W projektancie w kroku, w którym chcesz dodać nową akcję, wybierz pozycję Nowy krok. Alternatywnie, aby dodać nową akcję między krokami, przenieś wskaźnik na strzałkę między tymi krokami, wybierz znak plus (+) i wybierz pozycję Dodaj akcję.

2. W polu wyszukiwania Wybierz operację wprowadź tożsamość usług komunikacyjnych. Z listy akcji wybierz pozycję Utwórz użytkownika.

   

3. Podaj ciąg Połączenie ion. Można to znaleźć na platformie Microsoft Azure w ramach zasobu usługi Azure Communication Service w opcji Klucze z menu > po lewej stronie Połączenie ion String

   

4. Podaj nazwę Połączenie ion

5. Kliknij pozycję Utwórz

   Ta akcja spowoduje utworzenie identyfikatora użytkownika, który jest tożsamością użytkownika usług komunikacyjnych. Ponadto jeśli klikniesz pozycję "Pokaż opcje zaawansowane" i wybierzesz zakres tokenu, akcja zwróci również token dostępu i jego czas wygaśnięcia z określonym zakresem.

   

   

Wystawianie tokenu dostępu użytkownika

Po utworzeniu tożsamości usług komunikacyjnych możesz użyć akcji Wystawianie tokenu dostępu użytkownika w celu wystawienia tokenu dostępu. W poniższych krokach pokazano, jak wykonać następujące czynności:

1. Dodaj nową akcję i wprowadź tożsamość usług komunikacyjnych w polu wyszukiwania. Z listy akcji wybierz pozycję Wystawianie tokenu dostępu użytkownika.

   

2. Następnie możesz użyć danych wyjściowych identyfikatora użytkownika z poprzedniego kroku Tworzenie użytkownika .

3. Określ zakres tokenu: VoIP lub czat. Dowiedz się więcej o tokenach i uwierzytelnianiu.

   

Spowoduje to uzyskanie tokenu dostępu i czasu wygaśnięcia z określonym zakresem.

Odwoływanie tokenów dostępu użytkowników

Po utworzeniu tożsamości usług komunikacyjnych możesz użyć akcji Wystawianie tokenu dostępu użytkownika w celu odwołania tokenu dostępu. W poniższych krokach pokazano, jak wykonać następujące czynności:

1. Dodaj nową akcję i wprowadź tożsamość usług komunikacyjnych w polu wyszukiwania. Z listy akcji wybierz pozycję Odwołaj tokeny dostępu użytkownika.

   

2. Określanie identyfikatora użytkownika

   

Spowoduje to odwołanie wszystkich tokenów dostępu użytkownika dla określonego użytkownika. Nie ma żadnych danych wyjściowych dla tej akcji.

Usuwanie użytkownika

Po utworzeniu tożsamości usług komunikacyjnych możesz użyć akcji Wystawianie tokenu dostępu użytkownika w celu usunięcia tokenu dostępu. W poniższych krokach pokazano, jak wykonać następujące czynności:

1. Dodaj nową akcję i wprowadź tożsamość usług komunikacyjnych w polu wyszukiwania. Z listy akcji wybierz pozycję Usuń użytkownika.

   

2. Określanie identyfikatora użytkownika

   

   Spowoduje to usunięcie użytkownika i odwołanie wszystkich tokenów dostępu użytkownika dla określonego użytkownika. Nie ma żadnych danych wyjściowych dla tej akcji.

Testowanie aplikacji logiki

Aby ręcznie uruchomić przepływ pracy, na pasku narzędzi projektanta wybierz pozycję Uruchom. Przepływ pracy powinien utworzyć użytkownika, wydać token dostępu dla tego użytkownika, usunąć go i usunąć użytkownika. Aby uzyskać więcej informacji, zobacz , jak uruchomić przepływ pracy. Dane wyjściowe tych akcji można sprawdzić po pomyślnym uruchomieniu przepływu pracy.

Używanie tożsamości do monitorowania i metryk

Identyfikator użytkownika ma pełnić rolę klucza podstawowego dla dzienników i metryk zbieranych za pośrednictwem usługi Azure Monitor. Aby wyświetlić wszystkie wywołania użytkownika, możesz na przykład skonfigurować uwierzytelnianie w taki sposób, aby mapować określoną tożsamość (lub tożsamości) usług Azure Communication Services na jednego użytkownika.

Dowiedz się więcej na temat pojęć związanych z uwierzytelnianiem, wywoływania diagnostyki za pośrednictwem analizy dzienników i dostępnych metryk.

Czyszczenie zasobów

Aby wyczyścić i usunąć subskrypcję usług Komunikacyjnych, usuń zasób lub grupę zasobów. Usunięcie grupy zasobów powoduje również usunięcie wszelkich innych skojarzonych z nią zasobów. Aby uzyskać więcej informacji, zobacz sekcję "Czyszczenie zasobów" w temacie Tworzenie zasobów usług komunikacyjnych i zarządzanie nimi.

Aby wyczyścić przepływ pracy aplikacji logiki i powiązane zasoby, zapoznaj się z artykułem Jak wyczyścić zasoby usługi Azure Logic Apps.

Następne kroki

W tym przewodniku Szybki start zawarto informacje na temat wykonywania następujących czynności:

• Wystawianie tokenów dostępu
• Zarządzanie tożsamościami

Dodawanie połączeń głosowych do aplikacji

Możesz również chcieć:

• Dowiedz się więcej o uwierzytelnianiu
• Dodawanie czatu do aplikacji
• Dowiedz się więcej o architekturze klienta i serwera
• Wdrażanie przykładu elementu hero usługi zaufanego uwierzytelniania

Następne kroki

W tym przewodniku Szybki start pokazano, jak utworzyć użytkownika, usunąć użytkownika, wydać użytkownikowi token dostępu i usunąć token dostępu użytkownika przy użyciu łącznika tożsamości usług Azure Communication Services. Aby dowiedzieć się więcej, zapoznaj się z dokumentacją usługi Azure Communication Services Identity Połączenie or.

Aby zobaczyć, jak tokeny są używane przez inne łączniki, zobacz , jak wysyłać wiadomość czatu z usługi Power Automate przy użyciu usług Azure Communication Services.

Aby dowiedzieć się więcej na temat wysyłania wiadomości e-mail przy użyciu łącznika poczty e-mail usług Azure Communication Services, zobacz Wysyłanie wiadomości e-mail w usłudze Power Automate za pomocą usług Azure Communication Services.