مكتبة عميل Azure Communication Common ل JavaScript - الإصدار 2.4.0

تحتوي هذه الحزمة على تعليمات برمجية شائعة لمكتبات Azure Communication Service.

الشروع في العمل

المتطلبات الأساسية

• اشتراك Azure.
• مورد Communication Services موجود. إذا كنت بحاجة إلى إنشاء المورد، يمكنك استخداممدخل Azure أو Azure PowerShellأو Azure CLI.
• بعد تثبيت الحزمة @azure/identity .

تثبيت

npm install @azure/communication-common

npm install @azure/identity

دعم المستعرض

حزمة JavaScript

لاستخدام مكتبة العميل هذه في المستعرض، تحتاج أولا إلى استخدام مجمع. للحصول على تفاصيل حول كيفية القيام بذلك، يرجى الرجوع إلى وثائق التجميع .

المفاهيم الأساسية

CommunicationTokenCredential وAzureCommunicationTokenCredential

هي CommunicationTokenCredential واجهة تستخدم لمصادقة مستخدم باستخدام خدمات الاتصالات، مثل الدردشة أو الاتصال.

يوفر AzureCommunicationTokenCredential طريقة ملائمة لإنشاء بيانات اعتماد لتنفيذ الواجهة المذكورة ويسمح لك بالاستفادة من منطق التحديث التلقائي المدمج.

بناء على السيناريو الخاص بك، قد ترغب في تهيئة الملف AzureCommunicationTokenCredential باستخدام:

• رمز ثابت (مناسب للعملاء الذين يقدمون وقتا طويلا معتادين على إرسال رسائل دردشة لمرة واحدة) أو
• وظيفة معاودة الاتصال التي تضمن حالة مصادقة مستمرة أثناء الاتصالات (مثالية على سبيل المثال لجلسات الاتصال الطويلة).
• بيانات اعتماد رمز مميز قادرة على الحصول على رمز مستخدم Entra. يمكنك توفير أي تنفيذ لواجهة TokenCredential. إنه مناسب للسيناريوهات التي تكون فيها هناك حاجة إلى رموز وصول مستخدم Entra للمصادقة مع خدمات الاتصالات.

يمكن الحصول على الرموز المميزة المتوفرة إما AzureCommunicationTokenCredential من خلال المنشئ أو عبر معاودة الاتصال بتجديد المعلومات للرمز المميز باستخدام مكتبة Azure Communication Identity.

أمثلة

إنشاء بيانات اعتماد باستخدام رمز مميز ثابت

بالنسبة للعملاء الذين يقضون وقتا طويلا، لا يلزم تحديث الرمز المميز عند انتهاء الصلاحية وقد AzureCommunicationTokenCredential يتم إنشاء مثيل باستخدام رمز مميز ثابت.

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

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

إنشاء بيانات اعتماد مع معاودة الاتصال

نفترض هنا أن لدينا وظيفة fetchTokenFromMyServerForUser تقدم طلب شبكة لاسترداد سلسلة رمز JWT للمستخدم. نقوم بتمريره إلى بيانات الاعتماد لجلب رمز مميز ل Bob من الخادم الخاص بنا. سيستخدم خادمنا مكتبة Azure Communication Identity لإصدار الرموز المميزة. من الضروري أن fetchTokenFromMyServerForUser تقوم الدالة بإرجاع رمز مميز صالح (مع تعيين تاريخ انتهاء صلاحية في المستقبل) في جميع الأوقات.

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 إلى صواب إلى استدعاء الدالة عندما tokenRefresher يقترب الرمز المميز من انتهاء الصلاحية.

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

قم بإنشاء بيانات اعتماد مع التحديث الاستباقي والرمز المميز الأولي

التمرير initialToken هو تحسين اختياري لتخطي المكالمة الأولى إلى tokenRefresher. يمكنك استخدام هذا لفصل التمهيد عن التطبيق الخاص بك عن دورات تحديث الرمز المميز اللاحقة.

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

إنشاء بيانات اعتماد باستخدام بيانات اعتماد رمز مميز قادر على الحصول على رمز مستخدم Entra

بالنسبة للسيناريوهات التي يمكن فيها استخدام مستخدم Entra مع خدمات الاتصالات، تحتاج إلى تهيئة أي تنفيذ لواجهة TokenCredential وتوفيرها إلى EntraCommunicationTokenCredentialOptions. إلى جانب ذلك، يجب عليك توفير URI لمورد Azure Communication Services والنطاقات المطلوبة للرمز المميز لمستخدم Entra. تحدد هذه النطاقات الأذونات الممنوحة للرمز المميز.

يجب استخدام هذا الأسلوب لتفويض مستخدم Entra بترخيص Teams لاستخدام ميزات قابلية توسعة هاتف Teams من خلال مورد Azure Communication Services. هذا يتطلب توفير النطاق https://auth.msft.communication.azure.com/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);

السيناريوهات الأخرى لمستخدمي Entra لاستخدام Azure Communication Services موجودة حاليا في مرحلة المعاينة فقط ويجب عدم استخدامها في الإنتاج. تتبع نطاقات هذه السيناريوهات التنسيق https://communication.azure.com/clients/<ACS Scope>. إذا لم يتم توفير نطاقات محددة، تعيين النطاقات الافتراضية إلى 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);

استكشاف الأخطاء وإصلاحها

• تم تحديد رمز مميز غير صالح: تأكد من أن الرمز المميز الذي تقوم بتمريره إلى المنشئ AzureCommunicationTokenCredential أو إلى معاودة tokenRefresher الاتصال هو سلسلة رمز JWT المميز العارية. على سبيل المثال، إذا كنت تستخدم مكتبة Azure Communication Identity أو واجهة برمجة تطبيقات REST للحصول على الرمز المميز، فتأكد من تمرير جزء كائن الاستجابة فقط token .

تسجيل

قد يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. لمشاهدة سجل طلبات واستجابات HTTP، قم بتعيين متغير البيئة AZURE_LOG_LEVEL إلى info. بدلا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق استدعاء setLogLevel في @azure/logger:

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

setLogLevel("info");

الخطوات التالية

• قراءة المزيد حول الرموز المميزة لوصول مستخدم الاتصال

المساهمه

إذا كنت ترغب في المساهمة في هذه المكتبة، فيرجى قراءة دليل المساهمة لمعرفة المزيد حول كيفية إنشاء التعليمات البرمجية واختبارها.

المشاريع ذات الصلة

• Microsoft Azure SDK ل Javascript