كتابة رمز مصادقة تطبيق العميل

مقالة
03/25/2023

بعد إعداد مثيل Azure Digital Twins والمصادقة، يمكنك إنشاء تطبيق عميل ستستخدمه للتفاعل مع المثيل. بمجرد إعداد مشروع عميل بداية، ستحتاج إلى كتابة التعليمات البرمجية في تطبيق العميل هذا لمصادقته مقابل مثيل Azure Digital Twins.

يصادق Azure Digital Twins باستخدام الرموز المميزة لأمان Microsoft Entra استنادا إلى OAUTH 2.0. لمصادقة SDK، ستحتاج إلى الحصول على رمز حامل مع الأذونات الصحيحة إلى Azure Digital Twins، وتمريره مع استدعاءات واجهة برمجة التطبيقات الخاصة بك.

توضح هذه المقالة كيفية الحصول على بيانات الاعتماد باستخدام Azure.Identity مكتبة العميل. بينما تعرض هذه المقالة أمثلة التعليمات البرمجية في C#، مثل ما تكتبه ل .NET (C#) SDK، يمكنك استخدام إصدار Azure.Identity بغض النظر عن SDK الذي تستخدمه (لمزيد من المعلومات حول حزم SDK المتوفرة ل Azure Digital Twins، راجع واجهات برمجة تطبيقات Azure Digital Twins وSDKs.

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

أولا، أكمل خطوات الإعداد في إعداد مثيل ومصادقة. سيضمن هذا الإعداد أن لديك مثيل Azure Digital Twins وأن المستخدم الخاص بك لديه أذونات الوصول. بعد هذا الإعداد، تكون مستعدا لكتابة التعليمات البرمجية لتطبيق العميل.

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

المصادقة باستخدام مكتبة Azure.Identity

Azure.Identity هي مكتبة عميل توفر العديد من أساليب الحصول على بيانات الاعتماد التي يمكنك استخدامها للحصول على رمز حامل والمصادقة مع SDK الخاص بك. على الرغم من أن هذه المقالة تقدم أمثلة في C#، يمكنك العرض Azure.Identity لعدة لغات، بما في ذلك...

ثلاث طرق شائعة للحصول على بيانات الاعتماد في Azure.Identity هي:

يوفر DefaultAzureCredential تدفق مصادقة افتراضي TokenCredential للتطبيقات التي سيتم نشرها في Azure، وهو الخيار الموصى به للتطوير المحلي. كما يمكن تمكينه لتجربة الطريقتين الأخريين الموصى بهما في هذه المقالة؛ فإنه يلتف ManagedIdentityCredential ويمكن الوصول InteractiveBrowserCredential مع متغير التكوين.
يعمل ManagedIdentityCredential بشكل جيد في الحالات التي تحتاج فيها إلى هويات مدارة (MSI)، وهو مرشح جيد للعمل مع Azure Functions والنشر إلى خدمات Azure.
InteractiveBrowserCredential مخصص للتطبيقات التفاعلية، ويمكن استخدامه لإنشاء عميل SDK مصادق عليه.

توضح بقية هذه المقالة كيفية استخدام هذه الأساليب مع .NET (C#) SDK.

إضافة Azure.Identity إلى مشروع .NET الخاص بك

لإعداد مشروع .NET للمصادقة باستخدام Azure.Identity، أكمل الخطوات التالية:

قم بتضمين حزمة Azure.DigitalTwins.Core SDK والحزمة Azure.Identity في مشروعك. اعتمادا على الأدوات التي تختارها، يمكنك تضمين الحزم باستخدام مدير حزمة Visual Studio أو dotnet أداة سطر الأوامر.
أضف عبارات الاستخدام التالية إلى التعليمات البرمجية لمشروعك:
```
using Azure.DigitalTwins.Core;
using Azure.Identity;
using System;
```

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

طريقة DefaultAzureCredential

يوفر DefaultAzureCredential تدفق مصادقة افتراضي TokenCredential للتطبيقات التي سيتم نشرها في Azure، وهو الخيار الموصى به للتطوير المحلي.

لاستخدام بيانات اعتماد Azure الافتراضية، ستحتاج إلى عنوان URL لمثيل Azure Digital Twins (إرشادات للبحث).

فيما يلي نموذج التعليمات البرمجية لإضافته DefaultAzureCredential إلى مشروعك:

public class DefaultAzureCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new DefaultAzureCredential();
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

إشعار

توجد حاليا مشكلة معروفة تؤثر على DefaultAzureCredential فئة برنامج التضمين قد تؤدي إلى حدوث خطأ أثناء المصادقة. إذا واجهت هذه المشكلة، يمكنك محاولة إنشاء DefaultAzureCredential مثيل باستخدام المعلمة الاختيارية التالية لحلها: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

لمزيد من المعلومات حول هذه المشكلة، راجع المشكلات المعروفة في Azure Digital Twins.

إعداد بيانات اعتماد Azure المحلية

سيبحث النموذج باستخدام DefaultAzureCredential عن بيانات اعتماد في بيئتك المحلية، مثل تسجيل الدخول إلى Microsoft Azure في Azure CLI محلي أو في Visual Studio أو Visual Studio Code. ولهذا السبب، يجب تسجيل الدخول محلياً إلى Microsoft Azure من خلال أحد هذه الآليات المخصصة لإعداد بيانات الاعتماد للنموذج.

إذا كنت تستخدم Visual Studio أو Visual Studio Code لتشغيل نماذج التعليمات البرمجية، فتأكد من تسجيل الدخول إلى هذا المحرر بنفس بيانات اعتماد Azure التي تريد استخدامها للوصول إلى مثيل Azure Digital Twins. إذا كنت تستخدم نافذة CLI محلية az login ، فقم بتشغيل الأمر لتسجيل الدخول إلى حساب Azure الخاص بك. بعد ذلك، عند تشغيل نموذج التعليمات البرمجية، يجب أن تتم مصادقتك تلقائيا.

أسلوب ManagedIdentityCredential

يعمل الأسلوب ManagedIdentityCredential بشكل جيد في الحالات التي تحتاج فيها إلى هويات مدارة (MSI) - على سبيل المثال، عند المصادقة باستخدام Azure Functions.

وهذا يعني أنه يمكنك استخدام ManagedIdentityCredential في نفس المشروع مثل DefaultAzureCredential أو InteractiveBrowserCredential، لمصادقة جزء مختلف من المشروع.

لاستخدام بيانات اعتماد Azure الافتراضية، ستحتاج إلى عنوان URL لمثيل Azure Digital Twins (إرشادات للبحث). قد تحتاج أيضا إلى تسجيل تطبيق ومعرف التطبيق (العميل) للتسجيل.

في دالة Azure، يمكنك استخدام بيانات اعتماد الهوية المدارة مثل هذا:

public class ManagedIdentityCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        DigitalTwinsClient client;
        try
        {
            // To use the function app's system-assigned identity:
            ManagedIdentityCredential cred = new ManagedIdentityCredential();
            // To use a user-assigned identity for the function app:
            //ManagedIdentityCredential cred = new ManagedIdentityCredential("<uai-client-ID>");

            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

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

أسلوب InteractiveBrowserCredential

الأسلوب InteractiveBrowserCredential مخصص للتطبيقات التفاعلية وسيجلب مستعرض ويب للمصادقة. يمكنك استخدام هذا الأسلوب بدلا من DefaultAzureCredential في الحالات التي تحتاج فيها إلى مصادقة تفاعلية.

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

فيما يلي مثال على التعليمات البرمجية لإنشاء عميل SDK مصادق عليه باستخدام InteractiveBrowserCredential.

public class InteractiveBrowserCredentialSample
{
    // Your client / app registration ID
    private const string clientId = "<your-client-ID>";
    // Your tenant / directory ID
    private const string tenantId = "<your-tenant-ID>";
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new InteractiveBrowserCredential(tenantId, clientId);
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

إشعار

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

مصادقة Azure Functions

يحتوي هذا القسم على بعض خيارات التكوين المهمة في سياق المصادقة باستخدام Azure Functions. أولا، ستقرأ عن المتغيرات الموصى بها على مستوى الفئة ورمز المصادقة الذي سيسمح للوظيفة بالوصول إلى Azure Digital Twins. بعد ذلك، ستقرأ عن بعض خطوات التكوين النهائية لإكمالها لوظيفتك بعد نشر التعليمات البرمجية الخاصة بها إلى Azure.

كتابة التعليمات البرمجية للتطبيق

عند كتابة دالة Azure، ضع في اعتبارك إضافة هذه المتغيرات والرمز إلى دالتك:

التعليمات البرمجية لقراءة عنوان URL لخدمة Azure Digital Twins كمتغير بيئة أو إعداد تكوين. من الممارسات الجيدة قراءة عنوان URL للخدمة من متغير إعداد/بيئة التطبيق، بدلا من ترميزه في الوظيفة. في دالة Azure، قد تبدو التعليمات البرمجية لقراءة متغير البيئة كما يلي:
```
private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
```
لاحقا، بعد نشر الدالة، ستقوم بإنشاء وتعيين قيمة متغير البيئة لهذه التعليمات البرمجية للقراءة. للحصول على إرشادات حول كيفية القيام بذلك، انتقل إلى تكوين إعدادات التطبيق.
متغير ثابت لاستيعاب مثيل HttpClient. يعد إنشاء HttpClient مكلفا نسبيا، لذلك ستحتاج على الأرجح إلى إنشائه مرة واحدة باستخدام رمز المصادقة لتجنب إنشائه لكل استدعاء دالة.
```
private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
```
بيانات اعتماد الهوية المدارة. إنشاء بيانات اعتماد هوية مدارة ستستخدمها وظيفتك للوصول إلى Azure Digital Twins.
```
// To use the function app's system-assigned identity:
var cred = new ManagedIdentityCredential();
// To use a user-assigned identity for the function app:
//var cred = new ManagedIdentityCredential("<uai-client-ID>");
```
سيؤدي ترك المعلمة فارغة كما هو موضح أعلاه إلى إرجاع بيانات الاعتماد للهوية المعينة من قبل النظام لتطبيق الدالة، إذا كانت تحتوي على واحدة. لتحديد هوية معينة من قبل المستخدم بدلا من ذلك، قم بتمرير معرف عميل الهوية المعينة من قبل المستخدم إلى المعلمة .

لاحقا، بعد نشر الدالة، ستتأكد من أن هوية الدالة لديها إذن للوصول إلى واجهات برمجة تطبيقات Azure Digital Twins. للحصول على إرشادات حول كيفية القيام بذلك، انتقل إلى تعيين دور وصول.
DigitalTwinsClient متغير محلي. أضف المتغير داخل دالتك للاحتفاظ بمثيل عميل Azure Digital Twins. لا تجعل هذا المتغير ثابتا داخل الفئة الخاصة بك.
```
var client = new DigitalTwinsClient(
    new Uri(adtInstanceUrl),
    cred,
    new DigitalTwinsClientOptions
    {
        Transport = new HttpClientTransport(singletonHttpClientInstance)
    });
```
فحص فارغ ل adtInstanceUrl. أضف التحقق الفارغ ثم قم بتضمين منطق الدالة في كتلة try/catch لالتقاط أي استثناءات.

بعد إضافة هذه المتغيرات إلى دالة، قد تبدو التعليمات البرمجية للدالة مثل المثال التالي.

// Default URL for triggering event grid function in the local environment.
// http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname}
//<Function_dependencies>
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using System;
using System.Net.Http;
//</Function_dependencies>

namespace DigitalTwins_Samples
{
    public class DigitalTwinsIngestFunctionSample
    {
        // Your Digital Twin URL is stored in an application setting in Azure Functions
        // <ADT_service_URL>
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        // </ADT_service_URL>
        // <HTTP_client>
        private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
        // </HTTP_client>

        [FunctionName("TwinsFunction")]
        public void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");
            try
            {
                // Authenticate with Digital Twins
                // <ManagedIdentityCredential>
                // To use the function app's system-assigned identity:
                var cred = new ManagedIdentityCredential();
                // To use a user-assigned identity for the function app:
                //var cred = new ManagedIdentityCredential("<uai-client-ID>");
                // </ManagedIdentityCredential>
                // <DigitalTwinsClient>
                var client = new DigitalTwinsClient(
                    new Uri(adtInstanceUrl),
                    cred,
                    new DigitalTwinsClientOptions
                    {
                        Transport = new HttpClientTransport(singletonHttpClientInstance)
                    });
                // </DigitalTwinsClient>
                log.LogInformation($"ADT service client connection created.");

                // Add your business logic here.
            }
            catch (Exception e)
            {
                log.LogError(e.Message);
            }
        }
    }
}

عند الانتهاء من التعليمات البرمجية للدالة، بما في ذلك إضافة المصادقة ومنطق الدالة، انشر التطبيق إلى Azure

تكوين التطبيق المنشور

وأخيرا، أكمل خطوات التكوين التالية لدالة Azure المنشورة للتأكد من أنها يمكنها الوصول إلى مثيل Azure Digital Twins.

قم بتشغيل الأوامر التالية في Azure Cloud Shell أو Azure CLI محلي.

إشعار

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

تعيين دور وصول

تتطلب دالة Azure تمرير رمز مميز للحامل إليه. للتأكد من تمرير الرمز المميز للحامل، امنح تطبيق الدالة دور مالك بيانات Azure Digital Twins لمثيل Azure Digital Twins، والذي سيمنح تطبيق الوظيفة الإذن لتنفيذ أنشطة مستوى البيانات على المثيل.

استخدم الأمر التالي لإنشاء هوية مدارة من قبل النظام لوظيفتك (إذا كانت الدالة تحتوي بالفعل على واحدة، فسيطبع هذا الأمر تفاصيلها). لاحظ الحقل في principalId الإخراج. ستستخدم هذا المعرف للإشارة إلى الدالة بحيث يمكنك منحها أذونات في الخطوة التالية.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
principalId استخدم القيمة في الأمر التالي لإعطاء الوظيفة دور مالك بيانات Azure Digital Twins لمثيل Azure Digital Twins.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

تكوين إعدادات التطبيق

بعد ذلك، اجعل عنوان URL لمثيل Azure Digital Twins الخاص بك قابلا للوصول إلى وظيفتك عن طريق تعيين متغير بيئة له.

تلميح

يتم إجراء عنوان URL لمثيل Azure Digital Twins عن طريق إضافة https:// إلى بداية اسم مضيف المثيل الخاص بك. لمشاهدة اسم المضيف، جنبا إلى جنب مع جميع خصائص المثيل الخاص بك، قم بتشغيل az dt show --dt-name <your-Azure-Digital-Twins-instance>.

يعين الأمر التالي متغير بيئة لعنون URL للمثيل الذي ستستخدمه وظيفتك كلما احتاجت إلى الوصول إلى المثيل.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

المصادقة عبر المستأجرين

Azure Digital Twins هي خدمة تدعم مستأجر Microsoft Entra واحدا فقط: المستأجر الرئيسي من الاشتراك حيث يوجد مثيل Azure Digital Twins.

ونتيجة لذلك، تتطلب الطلبات إلى واجهات برمجة تطبيقات Azure Digital Twins مستخدما أو كيان خدمة يشكل جزءا من نفس المستأجر حيث يوجد مثيل Azure Digital Twins. لمنع المسح الضار لنقاط نهاية Azure Digital Twins، سيتم إرجاع الطلبات التي تحتوي على رموز الوصول المميزة من خارج المستأجر الأصلي رسالة خطأ "لم يتم العثور على 404 مجال فرعي". سيتم إرجاع هذا الخطأ حتى إذا تم منح المستخدم أو كيان الخدمة مالك بيانات Azure Digital Twins أو دور قارئ بيانات Azure Digital Twins من خلال تعاون Microsoft Entra B2B.

إذا كنت بحاجة إلى الوصول إلى مثيل Azure Digital Twins باستخدام حساب مستخدم أو كيان خدمة ينتمي إلى مستأجر مختلف عن المثيل، يمكنك الحصول على كل هوية موحدة من مستأجر آخر يطلب رمزا مميزا من مستأجر "المنزل" لمثيل Azure Digital Twins.

إحدى الطرق للقيام بذلك هي مع أمر CLI التالي، حيث <home-tenant-ID> هو معرف مستأجر Microsoft Entra الذي يحتوي على مثيل Azure Digital Twins:

az account get-access-token --tenant <home-tenant-ID> --resource https://digitaltwins.azure.net

بعد طلب ذلك، ستتلقى الهوية رمزا مميزا تم إصداره لمورد https://digitaltwins.azure.net Microsoft Entra، والذي يحتوي على مطالبة معرف مستأجر مطابقة لمثيل Azure Digital Twins. يجب أن يسمح استخدام هذا الرمز المميز في طلبات واجهة برمجة التطبيقات أو مع التعليمات البرمجية الخاصة بك Azure.Identity للهوية الموحدة بالوصول إلى مورد Azure Digital Twins.

يمكنك أيضا تحديد المستأجر الرئيسي في خيارات بيانات الاعتماد في التعليمات البرمجية الخاصة بك.

يوضح المثال التالي كيفية تعيين نموذج قيمة معرف المستأجر ل InteractiveBrowserTenantId في DefaultAzureCredential الخيارات:

public class DefaultAzureCredentialOptionsSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    private static DefaultAzureCredentialOptions credentialOptions = new DefaultAzureCredentialOptions()
    {
        ExcludeSharedTokenCacheCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        TenantId = "<your-Azure-Active-Directory-tenant-ID>"
    };

    private static DefaultAzureCredential credential = new DefaultAzureCredential(credentialOptions);

    DigitalTwinsClient client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
}

هناك خيارات مماثلة متاحة لتعيين مستأجر للمصادقة باستخدام Visual Studio وVisual Studio Code. لمزيد من المعلومات حول الخيارات المتاحة، راجع وثائق DefaultAzureCredentialOptions.

أساليب بيانات الاعتماد الأخرى

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

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

اقرأ المزيد حول كيفية عمل الأمان في Azure Digital Twins:

أمان حلول Azure Digital Twins

أو، الآن بعد إعداد المصادقة، انتقل إلى إنشاء النماذج وإدارتها في المثيل الخاص بك:

إدارة نماذج DTDL

مشاركة عبر

كتابة رمز مصادقة تطبيق العميل

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

المصادقة باستخدام مكتبة Azure.Identity

إضافة Azure.Identity إلى مشروع .NET الخاص بك

طريقة DefaultAzureCredential

إعداد بيانات اعتماد Azure المحلية

أسلوب ManagedIdentityCredential

أسلوب InteractiveBrowserCredential

مصادقة Azure Functions

كتابة التعليمات البرمجية للتطبيق

تكوين التطبيق المنشور

تعيين دور وصول

تكوين إعدادات التطبيق

المصادقة عبر المستأجرين

أساليب بيانات الاعتماد الأخرى

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

الملاحظات

الملاحظات

الموارد الإضافية