التشغيل السريع: إنشاء رموز الوصول المميزة وإدارتها

تسمح الرموز المميزة للوصول ل Azure Communication Services SDKs بالمصادقة مباشرة مقابل Azure Communication Services كهوية معينة. ستحتاج إلى إنشاء رموز مميزة للوصول إذا كنت تريد أن ينضم المستخدمون إلى مكالمة أو مؤشر ترابط دردشة داخل التطبيق الخاص بك.

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

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• مورد "خدمات الاتصال" النشطة وسلسلة الاتصال. إنشاء مورد Communication Services
• تثبيت Azure CLI.

الإعداد

إضافة الملحق

أضف ملحق Azure Communication Services ل Azure CLI باستخدام az extension الأمر .

az extension add --name communication

تسجيل الدخول إلى واجهة سطر الأوامر Azure

ستحتاج إلى تسجيل الدخول إلى Azure CLI. يمكنك تسجيل الدخول لتشغيل az login الأمر من المحطة الطرفية وتوفير بيانات الاعتماد الخاصة بك.

(اختياري) استخدام عمليات هوية Azure CLI دون تمرير سلسلة الاتصال

يمكنك تكوين AZURE_COMMUNICATION_CONNECTION_STRING متغير البيئة لاستخدام عمليات هوية Azure CLI دون الحاجة إلى استخدام --connection_string لتمرير سلسلة الاتصال. لتكوين متغير بيئة، افتح إطار وحدة التحكم وحدد نظام التشغيل من علامات التبويب أدناه. استبدل <yourConnectionString> بسلسلة الاتصال الفعلية الخاصة بك.

Windows

افتح إطار وحدة التحكم وأدخل الأمر التالي:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

بعد إضافة متغير البيئة، قد تحتاج إلى إعادة تشغيل أي برامج قيد التشغيل ستحتاج إلى قراءة متغير البيئة، بما في ذلك إطار وحدة التحكم. على سبيل المثال، إذا كنت تستخدم Visual Studio كمحرر، فعد تشغيل Visual Studio قبل تشغيل المثال.

ماك

تحرير .zshrc، وإضافة متغير البيئة:

export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"

بعد إضافة متغير البيئة، تشغيل source ~/.zshrc من إطار وحدة التحكم لجعل التغييرات فعالة. في حال قمت بإنشاء متغير البيئة مع فتح IDE الخاص بك قد تحتاج إلى إغلاق وإعادة فتح المحرر أو IDE أو shell للوصول إلى المتغير.

Linux

تحرير .bash_profile، وإضافة متغير البيئة:

export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"

بعد إضافة متغير البيئة، تشغيل source ~/.bash_profile من إطار وحدة التحكم لجعل التغييرات فعالة. في حال قمت بإنشاء متغير البيئة مع فتح IDE الخاص بك قد تحتاج إلى إغلاق وإعادة فتح المحرر أو IDE أو shell للوصول إلى المتغير.

تخزين الرمز المميز للوصول في متغير بيئة

لتكوين متغير بيئة، افتح إطار وحدة التحكم وحدد نظام التشغيل من علامات التبويب أدناه. استبدل <yourAccessToken> برمز الوصول الفعلي الخاص بك.

Windows

افتح إطار وحدة التحكم وأدخل الأمر التالي:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

بعد إضافة متغير البيئة، قد تحتاج إلى إعادة تشغيل أي برامج قيد التشغيل ستحتاج إلى قراءة متغير البيئة، بما في ذلك إطار وحدة التحكم. على سبيل المثال، إذا كنت تستخدم Visual Studio كمحرر، فعد تشغيل Visual Studio قبل تشغيل المثال.

ماك

تحرير .zshrc، وإضافة متغير البيئة:

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

بعد إضافة متغير البيئة، تشغيل source ~/.zshrc من إطار وحدة التحكم لجعل التغييرات فعالة. في حال قمت بإنشاء متغير البيئة مع فتح IDE الخاص بك قد تحتاج إلى إغلاق وإعادة فتح المحرر أو IDE أو shell للوصول إلى المتغير.

Linux

تحرير .bash_profile، وإضافة متغير البيئة:

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

بعد إضافة متغير البيئة، تشغيل source ~/.bash_profile من إطار وحدة التحكم لجعل التغييرات فعالة. في حال قمت بإنشاء متغير البيئة مع فتح IDE الخاص بك قد تحتاج إلى إغلاق وإعادة فتح المحرر أو IDE أو shell للوصول إلى المتغير.

العمليات

إنشاء هوية

لإنشاء رموز مميزة للوصول، تحتاج إلى هوية. تحتفظ Azure Communication Services بدليل هوية خفيف لهذا الغرض. user create استخدم الأمر لإنشاء إدخال جديد في الدليل باستخدام فريد Id. الهوية مطلوبة لاحقا لإصدار رموز الوصول المميزة.

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

• استبدل <yourConnectionString> سلسلة الاتصال الخاص بك.

إنشاء هوية وإصدار رمز مميز للوصول في نفس الطلب

قم بتشغيل الأمر التالي لإنشاء هوية Communication Services وإصدار رمز مميز للوصول لها في نفس الوقت. scopes تحدد المعلمة مجموعة من أذونات وأدوار الرمز المميز للوصول. لمزيد من المعلومات، راجع قائمة الإجراءات المدعومة في المصادقة على Azure Communication Services.

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

قم بإجراء هذا الاستبدال في التعليمات البرمجية:

• استبدل <yourConnectionString> سلسلة الاتصال الخاص بك.

إصدار الرمز المميز للوصول

قم بتشغيل الأمر التالي لإصدار رمز مميز للوصول لهوية Communication Services. scopes تحدد المعلمة مجموعة من أذونات وأدوار الرمز المميز للوصول. لمزيد من المعلومات، راجع قائمة الإجراءات المدعومة في المصادقة على Azure Communication Services.

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

قم بإجراء هذا الاستبدال في التعليمات البرمجية:

• استبدل <yourConnectionString> سلسلة الاتصال الخاص بك.
• استبدل <userId> بمعرف المستخدم الخاص بك.

رموز الوصول المميزة هي بيانات اعتماد قصيرة الأجل تحتاج إلى إعادة إصدار. قد يؤدي عدم القيام بذلك إلى تعطيل تجربة مستخدمي التطبيق الخاص بك. تشير خاصية الاستجابة expires_on إلى فترة صلاحية الرمز المميز للوصول.

إصدار رمز الوصول المميز مع نطاقات متعددة

قم بتشغيل الأمر التالي لإصدار رمز مميز للوصول مع نطاقات متعددة لهوية Communication Services. scopes تحدد المعلمة مجموعة من أذونات وأدوار الرمز المميز للوصول. لمزيد من المعلومات، راجع قائمة الإجراءات المدعومة في نموذج الهوية.

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

قم بإجراء هذا الاستبدال في التعليمات البرمجية:

• استبدل <yourConnectionString> سلسلة الاتصال الخاص بك.
• استبدل <userId> بمعرف المستخدم الخاص بك.

رموز الوصول المميزة هي بيانات اعتماد قصيرة الأجل تحتاج إلى إعادة إصدار. قد يؤدي عدم القيام بذلك إلى تعطيل تجربة مستخدمي التطبيق الخاص بك. تشير خاصية الاستجابة expires_on إلى فترة صلاحية الرمز المميز للوصول.

تبادل رمز وصول Microsoft Entra المميز لمستخدم Teams للحصول على رمز مميز للوصول إلى هوية الاتصال

token get-for-teams-user استخدم الأمر لإصدار رمز مميز للوصول لمستخدم Teams الذي يمكن استخدامه مع Azure Communication Services SDKs.

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

قم بإجراء هذا الاستبدال في التعليمات البرمجية:

• استبدل <yourConnectionString> سلسلة الاتصال الخاص بك.
• استبدل <yourAadUser> ب Microsoft Entra userId الخاص بك.
• استبدل <yourAadApplication> بمعرف تطبيق Microsoft Entra.
• استبدل <yourAadToken> برمز الوصول المميز ل Microsoft Entra.

إبطال الرموز المميزة للوصول

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

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

قم بإجراء هذا الاستبدال في التعليمات البرمجية:

• استبدل <yourConnectionString> سلسلة الاتصال الخاص بك.
• استبدل <userId> بمعرف المستخدم الخاص بك.

حذف هوية

عند حذف هوية، يمكنك إبطال جميع الرموز المميزة للوصول النشطة ومنع المزيد من إصدار رموز الوصول المميزة للهوية. يؤدي القيام بذلك أيضا إلى إزالة جميع المحتويات المستمرة المقترنة بالهوية.

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

قم بإجراء هذا الاستبدال في التعليمات البرمجية:

• استبدل <yourConnectionString> سلسلة الاتصال الخاص بك.
• استبدل <userId> بمعرف المستخدم الخاص بك.

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• أحدث إصدار من .NET Core SDK لنظام التشغيل الخاص بك.
• مورد "خدمات الاتصال" النشطة وسلسلة الاتصال. إنشاء مورد Communication Services

التعليمة البرمجية النهائية

ابحث عن التعليمات البرمجية النهائية لهذا البداية السريعة في GitHub.

إعداد بيئتك

إنشاء تطبيق C# جديد

في نافذة موجه الأوامر، مثل cmd أو PowerShell أو Bash، قم بتشغيل dotnet new الأمر لإنشاء تطبيق وحدة تحكم جديد بالاسم AccessTokensQuickstart. يُنشئ هذا الأمر مشروع "مرحباً بالعالم" C# بسيطاً مع مصدر ملف واحد، Program.cs.

dotnet new console -o AccessTokensQuickstart

غيِّر الدليل الخاص بك إلى مجلد التطبيق الذي تم إنشاؤه حديثاً، واستخدم الأمر dotnet build لتحويل تطبيقك برمجياً.

cd AccessTokensQuickstart
dotnet build

يجب عرض إخراج "مرحبًا بالعالم" بسيط. إذا كان الأمر كذلك، فإن الإعداد الخاص بك يعمل بشكل صحيح، ويمكنك البدء في كتابة التعليمات البرمجية الخاصة ب Azure Communication Services.

تثبيت الحزمة

أثناء وجودك في دليل التطبيق، قم بتثبيت مكتبة هوية Azure Communication Services لحزمة .NET باستخدام الأمر dotnet add package.

dotnet add package Azure.Communication.Identity

إعداد إطار عمل التطبيق

في دليل المشروع، قم بما يلي:

1. افتح ملف Program.cs في محرر النص.
2. using إضافة توجيه لتضمين Azure.Communication.Identity مساحة الاسم.
3. قم بتحديث إعلان الطريقة Main لدعم التعليمة البرمجية غير المتزامنة.

للبدء، قم بتشغيل التعليمات البرمجية التالية:

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
        }
    }
}

مصادقة العميل

التهيئة CommunicationIdentityClient باستخدام سلسلة الاتصال الخاص بك. تقوم التعليمات البرمجية التالية، التي تضيفها إلى Main الأسلوب، باسترداد سلسلة الاتصال للمورد من متغير بيئة يسمى COMMUNICATION_SERVICES_CONNECTION_STRING.

لمزيد من المعلومات، راجع قسم "تخزين سلسلة الاتصال" في إنشاء موارد Communication Services وإدارتها.

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

بدلا من ذلك، يمكنك فصل نقطة النهاية ومفتاح الوصول عن طريق تشغيل التعليمات البرمجية التالية:

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

إذا قمت بالفعل بإعداد تطبيق Microsoft Entra، يمكنك المصادقة باستخدام معرف Microsoft Entra.

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

إنشاء هوية

لإنشاء رموز مميزة للوصول، تحتاج إلى هوية. تحتفظ Azure Communication Services بدليل هوية خفيف لهذا الغرض. استخدم الأسلوب createUser لإنشاء إدخال جديد في الدليل باستخدام Id فريد. الهوية مطلوبة لاحقا لإصدار رموز الوصول المميزة.

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

قم بتخزين الهوية المستلمة مع التعيين لمستخدمي التطبيق الخاص بك (على سبيل المثال، عن طريق تخزينها في قاعدة بيانات خادم التطبيق).

إصدار رمز مميز للوصول

بعد أن يكون لديك هوية Communication Services، استخدم GetToken الأسلوب لإصدار رمز مميز للوصول له. scopes تحدد المعلمة مجموعة من أذونات وأدوار الرمز المميز للوصول. لمزيد من المعلومات، راجع قائمة الإجراءات المدعومة في نموذج الهوية. يمكنك أيضا إنشاء مثيل communicationUser جديد استنادا إلى تمثيل سلسلة لهوية 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);

رموز الوصول المميزة هي بيانات اعتماد قصيرة الأجل تحتاج إلى إعادة إصدار. قد يؤدي عدم القيام بذلك إلى تعطيل تجربة مستخدمي التطبيق الخاص بك. تشير الخاصية expiresOn إلى فترة صلاحية الرمز المميزة للوصول.

تعيين وقت انتهاء صلاحية رمز مميز مخصص

وقت انتهاء صلاحية الرمز المميز الافتراضي هو 24 ساعة، ولكن يمكنك تكوينه عن طريق توفير قيمة بين ساعة و24 ساعة للمعلمة tokenExpiresInالاختيارية . عند طلب رمز مميز جديد، يوصى بتحديد الطول النموذجي المتوقع لجلسة اتصال لوقت انتهاء صلاحية الرمز المميز.

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

إنشاء هوية وإصدار رمز مميز في نفس الطلب

يمكنك استخدام CreateUserAndTokenAsync الأسلوب لإنشاء هوية Communication Services وإصدار رمز مميز للوصول لها في نفس الوقت. scopes تحدد المعلمة مجموعة من أذونات وأدوار الرمز المميز للوصول. لمزيد من المعلومات، راجع قائمة الإجراءات المدعومة في المصادقة على 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);

تحديث رمز مميز للوصول

لتحديث رمز مميز للوصول، مرر مثيل الكائن CommunicationUserIdentifier إلى GetTokenAsync. إذا قمت بتخزين Id وتحتاج إلى إنشاء CommunicationUserIdentifier جديد، يمكنك القيام بذلك عن طريق تمرير Id المخزن إلى مُنشئ CommunicationUserIdentifier على النحو التالي:

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

إبطال الرموز المميزة للوصول

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

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

حذف هوية

عند حذف هوية، يمكنك إبطال جميع الرموز المميزة للوصول النشطة ومنع المزيد من إصدار رموز الوصول المميزة للهوية. يؤدي القيام بذلك أيضا إلى إزالة جميع المحتويات المستمرة المقترنة بالهوية.

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

تشغيل التعليمات البرمجية

عند الانتهاء من إنشاء الرمز المميز للوصول، يمكنك تشغيل التطبيق من دليل التطبيق الخاص بك باستخدام dotnet run الأمر .

dotnet run

يصف إخراج التطبيق كل إجراء مكتمل:

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

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• إصداران نشيطان لـLTS وMaintenance LTS من Node.js (يُوصى بالإصدارين 8.11.1 و10.14.1).
• مورد "خدمات الاتصال" النشطة وسلسلة الاتصال. إنشاء مورد Communication Services

التعليمة البرمجية النهائية

ابحث عن التعليمات البرمجية النهائية لهذا البداية السريعة في GitHub.

إعداد بيئتك

إنشاء تطبيق Node.js جديد

في نافذة terminal أو Command Prompt، قم بإنشاء دليل جديد لتطبيقك، ثم افتحه.

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

قم بتشغيل npm init -y لإنشاء ملف package.json بالإعدادات الافتراضية.

npm init -y

تثبيت الحزمة

استخدم الأمر npm install لتثبيت خدمات اتصالات Azure للهوية SDK للجافا سكريبت.

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

يسرد الخيار --save المكتبة كتبعية في ملف package.json.

إعداد إطار عمل التطبيق

1. أنشئ ملفا باسم issue-access-token.js في دليل المشروع وأضف التعليمات البرمجية التالية:

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

مصادقة العميل

إنشاء CommunicationIdentityClient مثيل مع سلسلة الاتصال الخاص بك. تقوم التعليمات البرمجية التالية، التي تضيفها إلى Main الأسلوب، باسترداد سلسلة الاتصال للمورد من متغير بيئة يسمى COMMUNICATION_SERVICES_CONNECTION_STRING.

لمزيد من المعلومات، راجع قسم "تخزين سلسلة الاتصال" في إنشاء موارد Communication Services وإدارتها.

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

بدلا من ذلك، يمكنك فصل نقطة النهاية ومفتاح الوصول عن طريق تشغيل التعليمات البرمجية التالية:

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

إذا قمت بالفعل بإعداد تطبيق Microsoft Entra، يمكنك المصادقة باستخدام معرف Microsoft Entra.

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

إنشاء هوية

لإنشاء رموز مميزة للوصول، تحتاج إلى هوية. تحتفظ Azure Communication Services بدليل هوية خفيف لهذا الغرض. استخدم الأسلوب createUser لإنشاء إدخال جديد في الدليل باستخدام Id فريد. الهوية مطلوبة لاحقا لإصدار رموز الوصول المميزة.

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

قم بتخزين الهوية المستلمة مع التعيين لمستخدمي التطبيق الخاص بك (على سبيل المثال، عن طريق تخزينها في قاعدة بيانات خادم التطبيق).

إصدار رمز مميز للوصول

getToken استخدم الأسلوب لإصدار رمز مميز للوصول لهوية Communication Services. scopes تحدد المعلمة مجموعة من أذونات وأدوار الرمز المميز للوصول. لمزيد من المعلومات، راجع قائمة الإجراءات المدعومة في نموذج الهوية. يمكنك أيضا إنشاء مثيل جديد ل communicationUser استنادا إلى تمثيل سلسلة لهوية 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);

رموز الوصول المميزة هي بيانات اعتماد قصيرة الأجل تحتاج إلى إعادة إصدار. قد يؤدي عدم القيام بذلك إلى تعطيل تجربة مستخدمي التطبيق الخاص بك. تشير الخاصية expiresOn إلى فترة صلاحية الرمز المميزة للوصول.

تعيين وقت انتهاء صلاحية رمز مميز مخصص

وقت انتهاء صلاحية الرمز المميز الافتراضي هو 24 ساعة (1440 دقيقة)، ولكن يمكنك تكوينه عن طريق توفير قيمة بين 60 دقيقة و1440 دقيقة للمعلمة tokenExpiresInMinutesالاختيارية . عند طلب رمز مميز جديد، يوصى بتحديد الطول النموذجي المتوقع لجلسة اتصال لوقت انتهاء صلاحية الرمز المميز.

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

إنشاء هوية وإصدار رمز مميز في استدعاء أسلوب واحد

يمكنك استخدام createUserAndToken الأسلوب لإنشاء هوية Communication Services وإصدار رمز مميز للوصول لها في نفس الوقت. scopes تحدد المعلمة مجموعة من أذونات وأدوار الرمز المميز للوصول. مرة أخرى، يمكنك إنشاؤه مع 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);

تحديث رمز مميز للوصول

عند انتهاء صلاحية الرموز المميزة، ستحتاج بشكل دوري إلى تحديثها. التحديث سهل مجرد استدعاء getToken مرة أخرى بنفس الهوية التي تم استخدامها لإصدار الرموز المميزة. ستحتاج أيضا إلى توفير scopes الرموز المميزة المحدثة.

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

إبطال الرموز المميزة للوصول

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

await identityClient.revokeTokens(identityResponse);

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

حذف هوية

عند حذف هوية، يمكنك إبطال جميع الرموز المميزة للوصول النشطة ومنع المزيد من إصدار رموز الوصول المميزة للهوية. يؤدي القيام بذلك أيضا إلى إزالة جميع المحتويات المستمرة المقترنة بالهوية.

await identityClient.deleteUser(identityResponse);

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

تشغيل التعليمات البرمجية

من موجه وحدة التحكم، انتقل إلى الدليل الذي يحتوي على ملف issue-access-token.js ، ثم قم بتنفيذ الأمر التالي node لتشغيل التطبيق:

node ./issue-access-token.js

يصف إخراج التطبيق كل إجراء مكتمل:

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

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• Python 3.8+.
• مورد "خدمات الاتصال" النشطة وسلسلة الاتصال. إنشاء مورد Communication Services

التعليمة البرمجية النهائية

ابحث عن التعليمات البرمجية النهائية لهذا البداية السريعة في GitHub.

إعداد بيئتك

إنشاء تطبيق Python جديد

1. في نافذة terminal أو Command Prompt، قم بإنشاء دليل جديد لتطبيقك، ثم افتحه.

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

2. استخدم محرر نص لإنشاء ملف يسمى issue-access-tokens.py في الدليل الرئيسي للمشروع وإضافة بنية البرنامج، بما في ذلك معالجة الاستثناء الأساسية. ستضيف جميع التعليمات البرمجية المصدر لهذا التشغيل السريع إلى هذا الملف في الأقسام التالية.

   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)
   

تثبيت الحزمة

أثناء استمرارك في دليل التطبيق، قم بتثبيت Azure Communication Services Identity SDK لحزمة Python باستخدام pip install الأمر .

pip install azure-communication-identity

مصادقة العميل

التهيئة CommunicationIdentityClient باستخدام سلسلة الاتصال. تقوم التعليمات البرمجية التالية، التي تضيفها إلى try الكتلة، باسترداد سلسلة الاتصال للمورد من متغير بيئة يسمى COMMUNICATION_SERVICES_CONNECTION_STRING.

لمزيد من المعلومات، راجع قسم "تخزين سلسلة الاتصال" في إنشاء موارد Communication Services وإدارتها.

# 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)

بدلا من ذلك، إذا قمت بالفعل بإعداد تطبيق Microsoft Entra، يمكنك المصادقة باستخدام معرف Microsoft Entra.

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

إنشاء هوية

لإنشاء رموز مميزة للوصول، تحتاج إلى هوية. تحتفظ Azure Communication Services بدليل هوية خفيف لهذا الغرض. استخدم الأسلوب create_user لإنشاء إدخال جديد في الدليل باستخدام Id فريد. الهوية مطلوبة لاحقا لإصدار رموز الوصول المميزة.

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

قم بتخزين الهوية المستلمة مع التعيين لمستخدمي التطبيق الخاص بك (على سبيل المثال، عن طريق تخزينها في قاعدة بيانات خادم التطبيق).

إصدار رمز مميز للوصول

get_token استخدم الأسلوب لإصدار رمز مميز للوصول لهوية Communication Services. scopes تحدد المعلمة مجموعة من أذونات وأدوار الرمز المميز للوصول. لمزيد من المعلومات، راجع قائمة الإجراءات المدعومة في نموذج الهوية. يمكنك أيضا إنشاء مثيل جديد للمعلمة CommunicationUserIdentifier استنادا إلى تمثيل سلسلة لهوية 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)

رموز الوصول المميزة هي بيانات اعتماد قصيرة الأجل تحتاج إلى إعادة إصدار. قد يؤدي عدم القيام بذلك إلى تعطيل تجربة مستخدمي التطبيق الخاص بك. تشير خاصية الاستجابة expires_on إلى فترة صلاحية الرمز المميز للوصول.

تعيين وقت انتهاء صلاحية رمز مميز مخصص

وقت انتهاء صلاحية الرمز المميز الافتراضي هو 24 ساعة، ولكن يمكنك تكوينه عن طريق توفير قيمة بين ساعة و24 ساعة للمعلمة token_expires_inالاختيارية . عند طلب رمز مميز جديد، يوصى بتحديد الطول النموذجي المتوقع لجلسة اتصال لوقت انتهاء صلاحية الرمز المميز.

# 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)

إنشاء هوية وإصدار رمز مميز للوصول في نفس الطلب

يمكنك استخدام create_user_and_token الأسلوب لإنشاء هوية Communication Services وإصدار رمز مميز للوصول لها في نفس الوقت. scopes تحدد المعلمة مجموعة من أذونات وأدوار الرمز المميز للوصول. لمزيد من المعلومات، راجع قائمة الإجراءات المدعومة في المصادقة على 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)

تحديث رمز مميز للوصول

لتحديث رمز مميز للوصول، استخدم CommunicationUserIdentifier الكائن لإعادة إصدار رمز مميز عن طريق تمرير الهوية الموجودة:

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

إبطال الرموز المميزة للوصول

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

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

حذف هوية

عند حذف هوية، يمكنك إبطال جميع الرموز المميزة للوصول النشطة ومنع المزيد من إصدار رموز الوصول المميزة للهوية. يؤدي القيام بذلك أيضا إلى إزالة جميع المحتويات المستمرة المقترنة بالهوية.

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

تشغيل التعليمات البرمجية

من موجه وحدة التحكم، انتقل إلى الدليل الذي يحتوي على ملف issue-access-tokens.py ، ثم قم بتنفيذ الأمر التالي python لتشغيل التطبيق.

python ./issue-access-tokens.py

يصف إخراج التطبيق كل إجراء مكتمل:

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

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• Java Development Kit (JDK) الإصدار 8 أو أحدث.
• Apache Maven.
• مورد "خدمات الاتصال" النشطة وسلسلة الاتصال. إنشاء مورد Communication Services

التعليمة البرمجية النهائية

ابحث عن التعليمات البرمجية النهائية لهذا البداية السريعة في GitHub.

إعداد بيئتك

إنشاء تطبيق Java جديد

في نافذة terminal أو Command Prompt، انتقل إلى الدليل حيث تريد إنشاء تطبيق Java الخاص بك. لإنشاء مشروع Java من قالب maven-archetype-quickstart، قم بتشغيل التعليمات البرمجية التالية:

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

ستلاحظ أن generate المهمة تنشئ دليلا بنفس اسم artifactId. ضمن هذا الدليل، يحتوي الدليل src/main/javaعلى التعليمة البرمجية مصدر المشروع، بينما يحتوي دليل src/test/javaعلى مصدر الاختبار وملف pom.xml هو نموذج عنصر المشروع أو POM. يتم استخدام هذا الملف لمعلمات تكوين المشروع.

تثبيت حزم Communication Services

افتح ملف pom.xml في محرر النص. أضف عنصر التبعية التالي إلى مجموعة التبعيات:

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

ترشد هذه التعليمة البرمجية Maven لتثبيت Communication Services Identity SDK، والتي ستستخدمها لاحقا.

إعداد إطار عمل التطبيق

في دليل المشروع، قم بما يلي:

1. انتقل إلى دليل /src/main/java/com/communication/quickstart .
2. افتح ملف App.java في المحرر.
3. استبدل العبارة System.out.println("Hello world!"); .
4. إضافة توجيهات import.

استخدم الكود التالي للبدء:

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
    }
}

مصادقة العميل

إنشاء مثيل لـ CommunicationIdentityClient باستخدام مفتاح الوصول ونقطة النهاية للمورد الخاص بك. لمزيد من المعلومات، راجع قسم "تخزين سلسلة الاتصال" في إنشاء موارد Communication Services وإدارتها.

بالإضافة إلى ذلك، يمكنك تهيئة العميل مع أي عميل HTTP مخصص ينفذ الواجهة com.azure.core.http.HttpClient .

في ملف App.java ، أضف التعليمات البرمجية main التالية إلى الأسلوب :

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

بدلا من توفير نقطة النهاية ومفتاح الوصول، يمكنك توفير سلسلة الاتصال بالكامل باستخدام connectionString() الأسلوب .

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

إذا قمت بالفعل بإعداد تطبيق Microsoft Entra، يمكنك المصادقة باستخدام معرف Microsoft Entra.

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

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

إنشاء هوية

لإنشاء رموز مميزة للوصول، تحتاج إلى هوية. تحتفظ Azure Communication Services بدليل هوية خفيف لهذا الغرض. استخدم الأسلوب createUser لإنشاء إدخال جديد في الدليل باستخدام Id فريد.

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

الهوية التي تم إنشاؤها مطلوبة لاحقا لإصدار رموز الوصول المميزة. قم بتخزين الهوية المستلمة مع التعيين لمستخدمي التطبيق الخاص بك (على سبيل المثال، عن طريق تخزينها في قاعدة بيانات خادم التطبيق).

إصدار رمز مميز للوصول

getToken استخدم الأسلوب لإصدار رمز مميز للوصول لهوية Communication Services. scopes تحدد المعلمة مجموعة من أذونات وأدوار الرمز المميز للوصول. لمزيد من المعلومات، راجع قائمة الإجراءات المدعومة في نموذج الهوية.

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

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

رموز الوصول المميزة هي بيانات اعتماد قصيرة الأجل تحتاج إلى إعادة إصدار. قد يؤدي عدم القيام بذلك إلى تعطيل تجربة مستخدمي التطبيق الخاص بك. تشير الخاصية expiresAt إلى فترة صلاحية الرمز المميزة للوصول.

تعيين وقت انتهاء صلاحية رمز مميز مخصص

وقت انتهاء صلاحية الرمز المميز الافتراضي هو 24 ساعة، ولكن يمكنك تكوينه عن طريق توفير قيمة بين ساعة و24 ساعة للمعلمة tokenExpiresInالاختيارية . عند طلب رمز مميز جديد، يوصى بتحديد الطول النموذجي المتوقع لجلسة اتصال لوقت انتهاء صلاحية الرمز المميز.

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

إنشاء هوية وإصدار رمز مميز في طلب واحد

بدلا من ذلك، يمكنك استخدام أسلوب "createUserAndToken" لإنشاء إدخال جديد في الدليل مع فريد Id وإصدار رمز مميز للوصول في نفس الوقت.

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

تحديث رمز مميز للوصول

لتحديث رمز مميز للوصول، استخدم CommunicationUserIdentifier الكائن لإعادة إصداره:

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

إبطال رمز مميز للوصول

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

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

حذف هوية

عند حذف هوية، يمكنك إبطال جميع الرموز المميزة للوصول النشطة ومنع المزيد من إصدار رموز الوصول المميزة للهوية. يؤدي القيام بذلك أيضا إلى إزالة جميع المحتويات المستمرة المقترنة بالهوية.

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

تشغيل التعليمات البرمجية

انتقل إلى الدليل الذي يحتوي على ملف pom.xml ، ثم قم بتجميع المشروع باستخدام الأمر التالي mvn :

mvn compile

ثم قم بإنشاء الحزمة:

mvn package

قم بتشغيل الأمر التالي mvn لتنفيذ التطبيق:

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

يصف إخراج التطبيق كل إجراء مكتمل:

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

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

• مورد Azure Communication Services

إنشاء الرموز المميزة للوصول

في مدخل Azure، انتقل إلى نافذة "Identities & User Access Tokens" غير المُكتملة داخل مورد Communication Services الخاص بك.

اختر نطاق الرموز المميزة للوصول. يُمكنك تحديد لا شيء، أو واحد، أو العديد. انقر فوق "Generate".

سترى هوية ما والرمز المميز لوصول المستخدم المتوافق الذي تم إنشاؤه. يُمكنك نسخ هذه السلاسل واستخدامها في نماذج التطبيقات وسيناريوهات الاختبار الأخرى.

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

• حساب Azure باشتراك نشط - أنشئ حساب Azure مجانًا

• مورد خدمات اتصالات Azure نشط، أو قم بإنشاء مورد خدمات الاتصال .

• مورد Azure Logic Apps نشط (تطبيق منطقي)، أو إنشاء سير عمل تطبيق منطق الاستهلاك مع المشغل الذي تريد استخدامه. حاليا، يوفر موصل هوية Azure Communication Services إجراءات فقط، لذلك يتطلب تطبيق المنطق مشغلا، كحد أدنى.

إنشاء المستخدم

أضف خطوة جديدة في سير العمل باستخدام موصل هوية Azure Communication Services، واتبع هذه الخطوات في Power Automate مع فتح تدفق Power Automate في وضع التحرير.

1. على المصمم، ضمن الخطوة التي تريد إضافة الإجراء الجديد إليها، حدد خطوة جديدة. بدلا من ذلك، لإضافة الإجراء الجديد بين الخطوات، حرك المؤشر فوق السهم بين هذه الخطوات، وحدد علامة الجمع (+)، وحدد إضافة إجراء.

2. في مربع البحث Choose an operation، أدخل Communication Services Identity. من قائمة الإجراءات، حدد إنشاء مستخدم.

   

3. قم بتوفير سلسلة الاتصال ion. يمكن العثور على هذا في Microsoft Azure، ضمن مورد Azure Communication Service، في خيار Keys من القائمة > اليسرى الاتصال String

   

4. توفير اسم الاتصال

5. انقر فوق "Create"

   سيؤدي هذا الإجراء إلى إخراج معرف المستخدم، وهو هوية مستخدم Communication Services. بالإضافة إلى ذلك، إذا نقرت فوق "Show advanced options" وحددت Token Scope، فسيخرج الإجراء أيضا رمز وصول ووقت انتهاء صلاحيته مع النطاق المحدد.

   

   

إصدار رمز مميز لوصول المستخدم

بعد أن يكون لديك هوية Communication Services، يمكنك استخدام الإجراء Issue a user access token لإصدار رمز مميز للوصول. ستوضح لك الخطوات التالية كيفية القيام بالتالي:

1. أضف إجراء جديدا وأدخل Communication Services Identity في مربع البحث. من قائمة الإجراءات، حدد Issue a user access token.

   

2. بعد ذلك، يمكنك استخدام إخراج معرف المستخدم من خطوة إنشاء مستخدم السابقة.

3. حدد نطاق الرمز المميز: VoIP أو الدردشة. تعرف على المزيد حول الرموز المميزة والمصادقة.

   

سيؤدي ذلك إلى إخراج رمز مميز للوصول ووقت انتهاء صلاحيته مع النطاق المحدد.

إبطال الرموز المميزة لوصول المستخدم

بعد أن يكون لديك هوية Communication Services، يمكنك استخدام الإجراء Issue a user access token لإبطال رمز مميز للوصول. ستوضح لك الخطوات التالية كيفية القيام بالتالي:

1. أضف إجراء جديدا وأدخل Communication Services Identity في مربع البحث. من قائمة الإجراءات، حدد إبطال الرموز المميزة لوصول المستخدم.

   

2. تحديد معرف المستخدم

   

سيؤدي ذلك إلى إبطال كافة الرموز المميزة لوصول المستخدم للمستخدم المحدد، ولا توجد مخرجات لهذا الإجراء.

حذف مستخدم

بعد أن يكون لديك هوية Communication Services، يمكنك استخدام الإجراء Issue a user access token لحذف رمز مميز للوصول . ستوضح لك الخطوات التالية كيفية القيام بالتالي:

1. أضف إجراء جديدا وأدخل Communication Services Identity في مربع البحث. من قائمة الإجراءات، حدد حذف مستخدم.

   

2. تحديد معرف المستخدم

   

   سيؤدي ذلك إلى إزالة المستخدم وإبطال كافة الرموز المميزة لوصول المستخدم للمستخدم المحدد، ولا توجد مخرجات لهذا الإجراء.

اختبر تطبيق المنطق الخاص بك

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

استخدام الهوية للمراقبة والمقاييس

يهدف معرف المستخدم إلى العمل كمفتاح أساسي للسجلات والمقاييس التي يتم جمعها من خلال Azure Monitor. لعرض جميع مكالمات المستخدم، على سبيل المثال، يمكنك إعداد المصادقة بطريقة تعين هوية Azure Communication Services (أو هويات) معينة لمستخدم واحد.

تعرف على المزيد حول مفاهيم المصادقة وتشخيص المكالمات من خلال تحليلات السجل والمقاييسالمتوفرة لك.

تنظيف الموارد

لتنظيف اشتراك Communication Services وحذفه، يمكنك حذف المورد أو مجموعة الموارد. يؤدي حذف مجموعة موارد أيضا إلى حذف أي موارد أخرى مقترنة بها. لمزيد من المعلومات، راجع قسم "تنظيف الموارد" في إنشاء موارد Communication Services وإدارتها.

لتنظيف سير عمل تطبيق المنطق والموارد ذات الصلة، راجع كيفية تنظيف موارد Azure Logic Apps.

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

في هذا البدء السريع، قد تعلّمت كيفية:

• إصدار رموز الوصول المميزة
• إدارة الهويات

إضافة مكالمات صوتية إلى تطبيقك

قد ترغب أيضًا في:

• التعرف على المصادقة
• إضافة دردشة إلى تطبيقك
• التعرف على تصميم العميل والخادم
• توزيع نموذج hero لخدمة المصادقة الموثوق بها

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

في هذا التشغيل السريع، تعلمت كيفية إنشاء مستخدم، وحذف مستخدم، وإصدار رمز وصول مميز للمستخدم، وإزالة رمز وصول المستخدم باستخدام موصل هوية Azure Communication Services. لمعرفة المزيد، تحقق من وثائق هوية Azure Communication Services الاتصال أو.

لمعرفة كيفية استخدام الرموز المميزة من قبل موصلات أخرى، تحقق من كيفية إرسال رسالة دردشة من Power Automate باستخدام Azure Communication Services.

لمعرفة المزيد حول كيفية إرسال بريد إلكتروني باستخدام موصل البريد الإلكتروني لخدمات اتصالات Azure، تحقق من إرسال رسالة بريد إلكتروني في Power Automate باستخدام Azure Communication Services.