إشعار
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تسجيل الدخول أو تغيير الدلائل.
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تغيير الدلائل.
توفر واجهة برمجة تطبيقات الويب لمدقق Power Apps آلية لتشغيل عمليات التحقق من التحليل الثابت مقابل التخصيصات والملحقات إلى النظام الأساسي Microsoft Dataverse. وهي متوفر للصناع والمطورين إجراء عمليات تدقيق قوية للتحليل الثابت على حلولها مقابل مجموعة من قواعد أفضل الممارسات لتحديد الأنماط التي تنطوي على مشاكل بسرعة. توفر الخدمة منطقا لميزة مدقق الحلول في مدخل صانع Power Apps ويتم تضمينها كجزء من التنفيذ التلقائي للتطبيقات المرسلة إلى Marketplace. يسمح التفاعل مع الخدمة مباشرةً بهذه الطريقة بتحليل الحلول المضمنة كجزء من البيئات المحلية (كافة الإصدارات المدعومة) والبيئات عبر الإنترنت.
للحصول على معلومات حول استخدام خدمة المدقق من التعليمات البرمجية PowerShell، راجع العمل مع الحلول باستخدام PowerShell.
ملاحظة
- لا يضمن استخدام مدقق Power Apps نجاح استيراد الحل. اختبارات التحليل الثابت التي يتم تنفيذها مقابل الحل لا تعرف الحالة المكونة لبيئة الوجهة، وقد يتوقف نجاح الاستيراد على حلول أو تكوينات أخرى في البيئة.
الأساليب البديلة
قبل قراءة التفاصيل حول كيفية التفاعل على المستوى الأدنى مع واجهات برمجة تطبيقات الويب، فكر في استخدام وحدة PowerShell الخاصة بنا، Microsoft.PowerApps.Checker.PowerShell، بدلاً من ذلك. إنها أداة مدعومة بالكامل متوفرة في PowerShell Gallery. القيد الحالي هو أنه يتطلب Windows PowerShell. إذا لم تتمكن من تلبية هذه المتطلبات، فإن التفاعل مع واجهات برمجة التطبيقات بشكل مباشر قد يكون الأسلوب الأفضل على الأرجح.
بدء الاستخدام
من الضروري العلم أن تحليل الحل بإمكانه أن يؤدي إلى عملية تشغيل طويلة. يمكن أن يستغرق الأمر عادةً ستين (60) ثانية إلى ما يزيد عن خمس (5) دقائق اعتمادًا على عوامل مختلفة، مثل عدد التخصيصات والتعليمات البرمجية وحجمها وتعقيدها. سير التحليل عبارة عن عملية غير متزامنة متعددة الخطوات تبدأ بتهيئة مهمة تحليل مع واجهة برمجة تطبيقات الحالة المستخدمة للاستعلام عن اكتمال تنفيذ المهمة. مثال عن سير التحليل على الشكل التالي:
- الحصول على الرمز المميز OAuth
- تحميل الاستدعاء (لكل ملف بشكل متوازٍ)
- تحليل الاستدعاء (يبدأ مهمة التحليل)
- حاله الاستدعاء حتى الانتهاء (حلقات مع الإيقاف المؤقت بين الاستدعاءات حتى الإشارة إلى النهاية أو تلبية الحد المعين)
- تنزيل النتائج من SAS URI المتوفر
هناك بعض التباينات القليلة:
- تضمين بحث القواعد أو مجموعة القواعد كخطوة سابقة. ومع ذلك، قد يكون تمرير معرف مجموعة قواعد مكوّنة أو تتضمن تعليمات برمجية ثابتة أسرع إلى حد ما. من المستحسن استخدام مجموعة قواعد تفي باحتياجاتك.
- يمكنك اختيار عدم استخدام آلية التحميل (راجع التحميل للاطلاع على القيود).
تحتاج إلى تحديد المتطلبات التالية:
راجع المقالات التالية للحصول على الوثائق الخاصة بواجهات برمجة تطبيقات فردية:
استرداد قائمة مجموعات القواعد
استرداد قائمة القواعد
تحميل ملف
استدعاء التحليل
تحقَّق من حالة التحليل
تحديد المنطقة الجغرافية
عند التفاعل مع خدمة المدقق Power Apps، يتم تخزين الملفات مؤقتا في Azure جنبا إلى جنب مع التقارير التي يتم إنشاؤها. باستخدام واجهة برمجة تطبيقات خاصة بالجغرافيا، يمكنك التحكم في المكان حيث يتم تخزين البيانات. يتم توجيه الطلبات لنقطة نهاية جغرافية إلى مثيل إقليمي استنادًا إلى الأداء الأفضل (زمن الانتقال للطالب). بعد أن يدخل الطلب إلى مثيل خدمة إقليمي، تبقى كافة المعالجات والبيانات الدائمة في هذه المنطقة المحددة. ستؤدي استجابات API معينه إلى إرجاع عناوين URL للمثيل الإقليمي للطلبات اللاحقة بمجرد توجيه مهمة تحليل إلى منطقة محددة. قد يكون لكل منطقة جغرافية إصدار مختلف من الخدمة يتم نشره في أي وقت محدد. يرجع استخدام إصدارات الخدمة المختلفة إلى عملية النشر الآمن متعددة المراحل، والتي تضمن التوافق الكامل للإصدار. وبالتالي، يجب استخدام نفس المنطقة الجغرافية لكل استدعاء API في دورة حياة التحليل، وقد يؤدي ذلك إلى تقليل وقت التنفيذ الكلي لأن البيانات قد لا تحتاج إلى الانتقال عبر مسافة سلكية بعيدة. فيما يلي المناطق الجغرافية المتوفرة:
| مركز بيانات Azure | Name | المنطقة الجغرَافِية | 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 |
| عامة | الإنتاج | سويسرا | switzerland.api.advisor.powerapps.com |
| عامة | الإنتاج | جنوب أفريقيا | southafrica.api.advisor.powerapps.com |
| عامة | الإنتاج | كوريا | korea.api.advisor.powerapps.com |
| عامة | الإنتاج | النرويج | norway.api.advisor.powerapps.com |
| عامة | الإنتاج | سنغافورة | singapore.api.advisor.powerapps.com |
| عامة | الإنتاج | السويد | sweden.api.advisor.powerapps.com |
| عامة | الإنتاج | بولندا | poland.api.advisor.powerapps.com |
| عامة | الإنتاج | إيطاليا | italy.api.advisor.powerapps.com |
| عامة | الإنتاج | الحكومة الأمريكية | gov.api.advisor.powerapps.us |
| عامة | الإنتاج | حكومة الولايات المتحدة L4 | high.api.advisor.powerapps.us |
| عامة | الإنتاج | وزارة الدفاع الأمريكية (DOD) مستوى 5 | mil.api.advisor.appsplatform.us |
| عامة | الإنتاج | الصين - مشغّل بواسطة 21Vianet | china.api.advisor.powerapps.cn |
ملاحظة
يمكنك اختيار استخدام جغرافيا المعاينة لدمج أحدث الميزات والتغييرات السابقة. ومع ذلك، لاحظ أن المعاينة تستخدم مناطق United States Azure فقط.
إدارة الإصدارات
من المستحسن تضمين معلمة سلسلة استعلام إصدار واجهة برمجة التطبيقات مع إصدار واجهة برمجة التطبيقات المطلوب، على الرغم من أن ذلك غير ضروري. إصدار 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. تتطلب نقطة النهاية هذه الآن المصادقة.
مجموعة قواعد مدقق الحلول
تحتوي مجموعة قواعد مدقق الحلول على مجموعة من القواعد الفعالة ذات فرص محددة للحصول على نتائج إيجابية خاطئة. إذا كنت تقوم بتشغيل التحليل في مقابل حل موجود، فمن المستحسن البدء بمجموعة القواعد هذه. هذه هي مجموعة القواعد التي تستخدمها ميزة مدقق الحلول.
مجموعة قواعد شهادة Marketplace
عند نشر التطبيقات على Marketplace، يجب أن تحصل على شهادة التطبيق الخاص بك. التطبيقات المنشورة على Marketplace مطلوبة لتلبية معيار عالي الجودة. تحتوي مجموعة قواعد شهادة Marketplace على القواعد التي تعد جزءا من مجموعة قواعد مدقق الحل، بالإضافة إلى قواعد أخرى لضمان نشر التطبيقات عالية الجودة فقط في المتجر. بعض قواعد شهادة Marketplace أكثر عرضة للإيجابيات الزائفة وقد تتطلب المزيد من الاهتمام لحلها.
العثور على معرف المستأجر
يلزم وجود معرف المستأجر للتفاعل مع واجهات برمجه التطبيقات التي تتطلب رمزًا مميزًا. راجع هذه المقالة للحصول على تفاصيل حول كيفية الحصول على معرف المستأجر. يمكنك أيضًا استخدام أوامر 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/"
بمجرد حصولك على هذه المعلومات، يمكنك اختيار استخدام Microsoft Authentication Library (MSAL) أو بعض الآليات الأخرى للحصول على الرمز المميز. فيما يلي مثال على كيفية القيام بذلك باستخدام 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.
راجع أيضًا
استرداد قائمة مجموعات القواعد
استرداد قائمة القواعد
تحميل ملف
استدعاء التحليل
تحقَّق من حالة التحليل