الملاحظات

استخدام واجهة برمجة التطبيقات على الويب لمدقق Power Apps

  • مقالة
  • قراءة خلال 7 دقائق

توفر واجهة برمجة التطبيقات على الويب لمدقق Power Apps آلية لتشغيل عمليات التحقق من التحليل الثابت مقابل التخصيصات والامتدادات لنظام Microsoft Dataverse الأساسي. وهي متوفر للمنشئين والمطورين لتمكينهم من إجراء عمليات تدقيق تحليلية غنية لحلولهم في مقابل مجموعة من قواعد أفضل الممارسات لتحديد الأنماط التي تنطوي على مشاكل بسرعة. توفر الخدمة منطق ميزة مدقق الحلول في مدخل منشئ Power Apps، وهي مضمنة كجزء من عملية التنفيذ التلقائي لتطبيقات المرسلة إلى AppSource. يسمح التفاعل مع الخدمة مباشرةً بهذه الطريقة بتحليل الحلول المضمنة كجزء من البيئات المحلية (كافة الإصدارات المدعومة) والبيئات عبر الإنترنت.

للحصول على معلومات حول استخدام خدمة المدقق من التعليمات البرمجية PowerShell، راجع العمل مع الحلول باستخدام PowerShell.

ملاحظة

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

الأساليب البديلة

قبل قراءة التفاصيل الخاصة بكيفية التفاعل مع واجهة برمجة التطبيقات على الويب، يمكنك الاستفادة بدلاً من ذلك من وحدة PowerShell،‏ Microsoft.PowerApps.Checker.PowerShell. إنها أداة مدعومة بشكل كامل ومتوفرة في معرض PowerShell. القيد الحالي هو أنه تحتاج إلى وجود Windows PowerShell. إذا لم تتمكن من تلبية هذه المتطلبات، فإن التفاعل مع واجهات برمجة التطبيقات بشكل مباشر قد يكون الأسلوب الأفضل على الأرجح.

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

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

  1. الحصول على الرمز المميز OAuth
  2. تحميل الاستدعاء (لكل ملف بشكل متوازٍ)
  3. تحليل الاستدعاء (يبدأ مهمة التحليل)
  4. حاله الاستدعاء حتى الانتهاء (حلقات مع الإيقاف المؤقت بين الاستدعاءات حتى الإشارة إلى النهاية أو تلبية الحد المعين)
  5. تنزيل النتائج من SAS URI المتوفر

هناك بعض التباينات القليلة:

  • تضمين بحث القواعد أو مجموعة القواعد كخطوة سابقة. ومع ذلك، قد يكون تمرير معرف مجموعة قواعد مكوّنة أو تتضمن تعليمات برمجية ثابتة أسرع إلى حد ما. من المستحسن استخدام مجموعة قواعد تفي باحتياجاتك.
  • يمكنك اختيار عدم استخدام آلية التحميل (راجع التحميل للاطلاع على القيود).

ستحتاج إلى تحديد ما يلي:

راجع الموضوعات التالية للحصول على الوثائق الخاصة بواجهات برمجة تطبيقات فردية:

استرداد قائمة مجموعات القواعد
استرداد قائمة القواعد
تحميل ملف
استدعاء التحليل
التحقق من حالة التحليل

تحديد المنطقة الجغرافية

عند التفاعل مع خدمة المدقق في Power Apps، يتم تخزين الملفات بشكل مؤقت في Azure مع التقارير التي تم إنشاؤها. باستخدام واجهة برمجة تطبيقات خاصة بالجغرافيا، يمكنك التحكم في المكان حيث يتم تخزين البيانات. يتم توجيه الطلبات لنقطة نهاية جغرافية إلى مثيل إقليمي استنادًا إلى الأداء الأفضل (زمن الانتقال للطالب). بعد أن يدخل الطلب إلى مثيل خدمة إقليمي، تبقى كافة المعالجات والبيانات الدائمة في هذه المنطقة المحددة. ستؤدي استجابات API معينه إلى إرجاع عناوين URL للمثيل الإقليمي للطلبات اللاحقة بمجرد توجيه مهمة تحليل إلى منطقة محددة. يُرجى العلم أنه يُحتمل وجود إصدار مختلف للخدمة المنشورة في كل منطقة جغرافية في وقت محدد بسبب عملية النشر الآمن المتعددة المراحل، مما يؤدي إلى ضمان توافق الإصدار الكامل. وبالتالي، يجب استخدام نفس المنطقة الجغرافية لكل استدعاء API في دورة حياة التحليل، وقد يؤدي ذلك إلى تقليل وقت التنفيذ الكلي لأن البيانات قد لا تحتاج إلى الانتقال عبر مسافة سلكية بعيدة. فيما يلي المناطق الجغرافية المتوفرة:

مركز بيانات Azure الاسم الموقع الجغرافي URI أساسي
سنة معاينة الولايات المتحدة الأمريكية unitedstatesfirstrelease.api.advisor.powerapps.com
سنة الإنتاج الولايات المتحدة الأمريكية unitedstates.api.advisor.powerapps.com
سنة الإنتاج أوروبا europe.api.advisor.powerapps.com
سنة الإنتاج آسيا asia.api.advisor.powerapps.com
سنة الإنتاج أستراليا australia.api.advisor.powerapps.com
سنة الإنتاج اليابان japan.api.advisor.powerapps.com
سنة الإنتاج الهند india.api.advisor.powerapps.com
سنة الإنتاج كندا canada.api.advisor.powerapps.com
سنة الإنتاج أمريكا الجنوبية southamerica.api.advisor.powerapps.com
سنة الإنتاج المملكة المتحدة unitedkingdom.api.advisor.powerapps.com
سنة الإنتاج فرنسا france.api.advisor.powerapps.com
سنة الإنتاج ألمانيا germany.api.advisor.powerapps.com
سنة الإنتاج الإمارات العربية المتحدة unitedarabemirates.api.advisor.powerapps.com
سنة الإنتاج US Government gov.api.advisor.powerapps.us
سنة الإنتاج US Government L4 high.api.advisor.powerapps.us
سنة الإنتاج US Government L5 (DOD) mil.api.advisor.appsplatform.us
سنة الإنتاج الصين - مشغّل بواسطة 21Vianet china.api.advisor.powerapps.cn

ملاحظة

يمكنك اختيار استخدام جغرافيا المعاينة لدمج أحدث الميزات والتغييرات السابقة. ومع ذلك، لاحظ أن المعاينة تستخدم مناطق Azure في الولايات المتحدة فقط.

تعيين الإصدار

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

https://unitedstatesfirstrelease.api.advisor.powerapps.com/api/ruleset?api-version=1.0

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

مجموعات القواعد والقواعد؟

يحتاج مدقق Power Apps إلى قائمة قواعد عند تشغيله. يمكن توفير هذه القواعد على شكل قواعد فردية أو تجميع قواعد، يُشار إليه باسم مجموعة قواعد. تعتبر مجموعة القواعد طريقة مناسبة لتحديد مجموعة من القواعد بدلاً من تحديد كل قاعدة بشكل فردي. على سبيل المثال، تستخدم ميزة مدقق الحلول مجموعة قواعد مسماة مدقق الحلول. عند إضافة قواعد جديدة أو ازالتها، ستتضمن الخدمة هذه التغييرات بشكل تلقائي من دون الحاجة إلى أي تغيير من قبل التطبيق المستهلك. إذا أردت ألا تتغير قائمة القواعد بشكل تلقائي كما ورد أعلاه، فيمكن تحديد القواعد بشكل فردي. بإمكان مجموعات القواعد أن تتضمن قاعدة أو أكثر بدون حد. بإمكان القاعدة أن تكون ضمن مجموعات قواعد متعددة أو ألا تكون ضمن أي مجموعة قواعد. يمكنك الحصول على قائمة بجميع مجموعات القواعد من خلال استدعاء واجهة برمجة التطبيقات على الشكل التالي: [Geographical URL]/api/ruleset. نقطة النهاية هذه مفتوحة ولا تحتاج إلى مصادقة.

مجموعة قواعد مدقق الحلول

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

مجموعة قواعد شهادة AppSource

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

العثور على معرف المستأجر

يلزم وجود معرف المستأجر للتفاعل مع واجهات برمجه التطبيقات التي تتطلب رمزًا مميزًا. راجع هذه المقالة للحصول على تفاصيل حول كيفية الحصول على معرف المستأجر. يمكنك أيضًا استخدام أوامر PowerShell لاسترداد معرف المستأجر. يستفيد المثال التالي من أوامر cmdlets في وحدة AzureAD.

# Login to AAD as your user
Connect-AzureAD

# Establish your tenant ID
$tenantId = (Get-AzureADTenantDetail).ObjectId

معرف المستأجر هو قيمة الخاصية ObjectId المرتجعة من Get-AzureADTenantDetail. يمكنك أيضًا رؤيته بعد تسجيل الدخول باستخدام Connect-AzureAD cmdlet في إخراج cmdlet. في هذه الحالة، سيكون باسم TenantId.

المصادقة والتخويل

لا يتطلب الاستعلام عن القواعد ومجموعات القواعد إلى الرمز المميز OAuth، ولكن كافة واجهات برمجة التطبيقات الأخرى تحتاج إلى الرمز المميز. تدعم واجهات برمجة التطبيقات اكتشاف التخويل من خلال استدعاء واجهات برمجة التطبيقات التي تحتاج إلى رمز مميز. ستكون الاستجابة رمز حالة HTTP غير مصرح 401 مع الرأس WWW-Authenticate وURI التخويل ومعرف المورد. ينبغي عليك أيضًا توفير معرف المستأجر في رأس x-ms-tenant-id. يمكنك مراجعة مصادقة وتخويل مدقق Power Apps لمزيد من المعلومات. يوجد أدناه مثال عن رأس الاستجابة المرتجع من طلب واجهة برمجة التطبيقات:

WWW-Authenticate →Bearer authorization_uri="https://login.microsoftonline.com/0082fff7-33c5-44c9-920c-c2009943fd1e", resource_id="https://api.advisor.powerapps.com/"

بمجرد أن تتوفر لديك هذه المعلومات، يمكنك اختيار استخدام مكتبة المصادقة (ADAL) في Azure Active Directory أو آلية أخرى للحصول على الرمز المميز. فيما يلي مثال عن كيفية القيام بذلك باستخدام C# ومكتبة ADAL، الإصدار 4.5.1:

// Call the status URI as it is the most appropriate to use with a GET.
// The GUID here is just random, but needs to be there.
Uri queryUri = new Uri($"{targetServiceUrl}/api/status/4799049A-E623-4B2A-818A-3A674E106DE5");
AuthenticationParameters authParams = null;

using (var client = new HttpClient())
{
    var request = new HttpRequestMessage(HttpMethod.Get, queryUri);
    request.Headers.Add("x-ms-tenant-id", tenantId.ToString());

    // NOTE - It is highly recommended to use async/await
    using (var response = client.SendAsync(request).GetAwaiter().GetResult())
    {
        if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
        {
            // NOTE - It is highly recommended to use async/await
            authParams = AuthenticationParameters.CreateFromUnauthorizedResponseAsync(response).GetAwaiter().GetResult();
        }
        else
        {
            throw new Exception($"Unable to connect to the service for authorization information. {response.ReasonPhrase}");
        }
    }
}

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

أمان النقل

للحصول على أفضل تشفير، تدعم خدمة المدقق الاتصالات باستخدام بروتوكول أمان طبقة النقل (TLS)‬، الإصدار 1.2 والإصدارات اللاحقة. للحصول على إرشادات حول أفضل ممارسات NET. حول TLS، راجع أفضل ممارسات بروتوكول أمان طبقة النقل (TLS) مع NET Framework..

تنسيق التقرير

نتيجة تحليل الحل هي ملف zip يحتوي على تقرير واحد أو أكثر بتنسيق JSON قياسي. يستند تنسيق التقرير إلى نتائج التحليل الثابتة المشار اليها كتنسيق Static Analysis Results Interchange‏ (SARIF). تتوفر أدوات للعرض والتفاعل مع مستندات SARIF. راجع موقع الويب هذا للحصول على التفاصيل. تستفيد هذه الخدمة من الإصدار الثاني من معيار OASIS.

راجع أيضًا

استرداد قائمة مجموعات القواعد
استرداد قائمة القواعد
تحميل ملف
استدعاء التحليل
التحقق من حالة التحليل

ملاحظة

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

سيستغرق الاستطلاع حوالي سبع دقائق. لا يتم جمع أي بيانات شخصية (بيان الخصوصية).