Pustaka klien Azure Communication Common untuk JavaScript - versi 2.4.2

Paket ini berisi kode umum untuk pustaka Azure Communication Service.

Memulai Langkah Pertama

Prasyarat

Sebuah langganan Azure.
Sumber daya Communication Services yang ada. Jika Anda perlu membuat sumber daya, Anda dapat menggunakan portal Azure, Azure PowerShell, atau Azure CLI.
Menginstal @azure/identity paket.

Menginstal

npm install @azure/communication-common

npm install @azure/identity

Dukungan peramban

Bundel JavaScript

Untuk menggunakan pustaka klien ini di browser, pertama-tama Anda perlu menggunakan bunder. Untuk detail tentang cara melakukan ini, silakan lihat dokumentasi bundling kami.

Konsep Utama

CommunicationTokenCredential dan AzureCommunicationTokenCredential

Ini CommunicationTokenCredential adalah antarmuka yang digunakan untuk mengautentikasi pengguna dengan Layanan Komunikasi, seperti Obrolan atau Panggilan.

Ini AzureCommunicationTokenCredential menawarkan cara yang nyaman untuk membuat kredensial yang mengimplementasikan antarmuka tersebut dan memungkinkan Anda memanfaatkan logika penyegaran otomatis bawaan.

Bergantung pada skenario Anda, Anda mungkin ingin menginisialisasi dengan AzureCommunicationTokenCredential :

token statis (cocok untuk klien berumur pendek yang digunakan untuk misalnya mengirim pesan Obrolan satu kali) atau
fungsi callback yang memastikan status otentikasi berkelanjutan selama komunikasi (ideal misalnya untuk sesi Panggilan yang panjang).
kredensial token yang mampu mendapatkan token pengguna Entra. Anda dapat menyediakan implementasi antarmuka TokenCredential apa pun. Sangat cocok untuk skenario di mana token akses pengguna Entra diperlukan untuk mengautentikasi dengan Communication Services.

Token yang dispolakan ke AzureCommunicationTokenCredential baik melalui konstruktor atau melalui callback penyegaran token dapat diperoleh menggunakan pustaka Identitas Komunikasi Azure.

Examples

Membuat kredensial dengan token statis

Untuk klien berumur pendek, menyegarkan token setelah kedaluwarsa tidak diperlukan dan AzureCommunicationTokenCredential dapat dibuat instance dengan token statis.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

const tokenCredential = new AzureCommunicationTokenCredential(
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjM2MDB9.adM-ddBZZlQ1WlN3pdPBOF5G4Wh9iZpxNP_fSvpF4cWs",
);

Membuat kredensial dengan callback

Di sini kita berasumsi bahwa kita memiliki fungsi fetchTokenFromMyServerForUser yang membuat permintaan jaringan untuk mengambil string token JWT untuk pengguna. Kami meneruskannya ke kredensial untuk mengambil token untuk Bob dari server kami sendiri. Server kami akan menggunakan pustaka Azure Communication Identity untuk menerbitkan token. Fungsi ini fetchTokenFromMyServerForUser harus mengembalikan token yang valid (dengan tanggal kedaluwarsa yang ditetapkan di masa mendatang) setiap saat.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

function fetchTokenFromMyServerForUser(user: string): Promise<string> {
  // Your custom implementation to fetch a token for the user
  return Promise.resolve("some-unique-token-for-" + user);
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchTokenFromMyServerForUser("bob@contoso.com"),
});

Membuat kredensial dengan penyegaran proaktif

Pengaturan refreshProactively ke true akan memanggil fungsi Anda tokenRefresher saat token mendekati kedaluwarsa.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

function fetchTokenFromMyServerForUser(user: string): Promise<string> {
  // Your custom implementation to fetch a token for the user
  return Promise.resolve("some-unique-token-for-" + user);
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchTokenFromMyServerForUser("bob@contoso.com"),
  refreshProactively: true,
});

Buat kredensial dengan penyegaran proaktif dan token awal

Lulus initialToken adalah pengoptimalan opsional untuk melewati panggilan pertama ke tokenRefresher. Anda dapat menggunakan ini untuk memisahkan boot dari aplikasi Anda dari siklus refresh token berikutnya.

import { AzureCommunicationTokenCredential } from "@azure/communication-common";

function fetchTokenFromMyServerForUser(user: string): Promise<string> {
  // Your custom implementation to fetch a token for the user
  return Promise.resolve("some-unique-token-for-" + user);
}

const tokenCredential = new AzureCommunicationTokenCredential({
  tokenRefresher: async () => fetchTokenFromMyServerForUser("bob@contoso.com"),
  refreshProactively: true,
  token:
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjM2MDB9.adM-ddBZZlQ1WlN3pdPBOF5G4Wh9iZpxNP_fSvpF4cWs",
});

Buat kredensial dengan kredensial token yang mampu mendapatkan token pengguna Entra

Untuk skenario di mana pengguna Entra dapat digunakan dengan Communication Services, Anda perlu menginisialisasi implementasi antarmuka TokenCredential apa pun dan memberikannya ke .EntraCommunicationTokenCredentialOptions Bersamaan dengan ini, Anda harus memberikan URI sumber daya Azure Communication Services dan cakupan yang diperlukan untuk token pengguna Entra. Cakupan ini menentukan izin yang diberikan ke token.

Pendekatan ini perlu digunakan untuk mengotorisasi pengguna Entra dengan lisensi Teams untuk menggunakan fitur Ekstensibilitas Telepon Teams melalui sumber daya Azure Communication Services Anda. Ini membutuhkan penyediaan https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls cakupan. Untuk lingkungan cloud GCCH, gunakan https://auth.msft.communication.azure.us/TeamsExtension.ManageCalls.

import { InteractiveBrowserCredential } from "@azure/identity";
import {
  EntraCommunicationTokenCredentialOptions,
  AzureCommunicationTokenCredential,
} from "@azure/communication-common";

const options = {
  tenantId: "<your-tenant-id>",
  clientId: "<your-client-id>",
  redirectUri: "<your-redirect-uri>",
};
const entraTokenCredential = new InteractiveBrowserCredential(options);

const entraTokenCredentialOptions: EntraCommunicationTokenCredentialOptions = {
  resourceEndpoint: "https://<your-resource>.communication.azure.com",
  tokenCredential: entraTokenCredential,
  scopes: ["https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls"],
};

const credential = new AzureCommunicationTokenCredential(entraTokenCredentialOptions);

Skenario lain bagi pengguna Entra untuk memanfaatkan Azure Communication Services saat ini hanya dalam tahap preview dan tidak boleh digunakan dalam produksi. Cakupan untuk skenario ini mengikuti format https://communication.azure.com/clients/<ACS Scope>. Jika cakupan tertentu tidak disediakan, cakupan default akan diatur ke https://communication.azure.com/clients/.default.

import { InteractiveBrowserCredential } from "@azure/identity";
import {
  EntraCommunicationTokenCredentialOptions,
  AzureCommunicationTokenCredential,
} from "@azure/communication-common";

const options = {
  tenantId: "<your-tenant-id>",
  clientId: "<your-client-id>",
  redirectUri: "<your-redirect-uri>",
};
const entraTokenCredential = new InteractiveBrowserCredential(options);

const entraTokenCredentialOptions: EntraCommunicationTokenCredentialOptions = {
  resourceEndpoint: "https://<your-resource>.communication.azure.com",
  tokenCredential: entraTokenCredential,
  scopes: ["https://communication.azure.com/clients/VoIP"],
};

const credential = new AzureCommunicationTokenCredential(entraTokenCredentialOptions);

Troubleshooting

Token tidak valid ditentukan: Pastikan token yang Anda teruskan ke AzureCommunicationTokenCredential konstruktor atau ke tokenRefresher callback adalah string token JWT kosong. Misalnya, jika Anda menggunakan pustaka Communication Identity Azure atau REST API untuk mendapatkan token, pastikan Anda hanya meneruskan bagian token dari objek respons.

Penebangan kayu

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Langkah berikutnya

Baca selengkapnya tentang Token akses pengguna Komunikasi

Contributing

Jika Anda ingin berkontribusi ke library ini, silakan baca panduan contributor untuk mempelajari lebih lanjut cara membuat dan menguji kode.

Microsoft Azure SDK untuk Javascript

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-06-03