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

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

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

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

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

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

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

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

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

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

تحتاج إلى تحديد المتطلبات التالية:

• أي منطقة جغرافية؟
• أي إصدار؟
• أي مجموعات قواعد وقواعد؟
• ما هو معرف المستأجر؟

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Login to Microsoft Entra ID 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/"

بمجرد حصولك على هذه المعلومات، يمكنك اختيار استخدام MSAL مكتبة مصادقة Microsoft أو آلية أخرى للحصول على الرمز المميز. فيما يلي مثال عن كيفية القيام بذلك باستخدام C# ومكتبة MSAL .NET:

// Substitute your own environment URL here.
string resource = "https://<env-name>.api.<region>.dynamics.com";

// Example Microsoft Entra app registration.
// For your custom apps, you will need to register them with Microsoft Entra ID yourself.
// See https://docs.microsoft.com/powerapps/developer/data-platform/walkthrough-register-app-azure-active-directory
var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
var redirectUri = "http://localhost"; // Loopback required for the interactive login.

var authBuilder = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
    .WithRedirectUri(redirectUri)
    .Build();
var scope = resource + "/.default";
string[] scopes = { scope };

AuthenticationResult tokenResult =
     await authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync();

للحصول على كود العمل الكامل، راجع ‬‏‫واجهة برمجة تطبيقات (API) الويب عينة QuickStart.

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

أمان النقل

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

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

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

(راجع أيضًا)

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