שימוש ב-API של בדיקת יישומי Power Apps

ממשק ה-API של Power Apps בודק היישומים מספק מנגנון להפעלת בדיקות ניתוח סטטיות כנגד התאמות אישיות והרחבות בפלטפורמת Microsoft Dataverse. הוא זמין עבור יוצרים ומפתחים לביצוע בדיקות ניתוח סטטי עשירות בפתרונות שלהם לעומת קבוצה של כללים המומלצים לעבודה כדי לזהות דפוסים בעייתיים במהירות. השירות מספק את הלוגיקה עבור תכונת בודק הפתרונות בפורטל יוצר היישומים של Power Apps והוא כלול כחלק מאוטומציה עבור אפליקציות שנשלחו ל- Marketplace. האינטראקציה הישירה עם השירות באופן זה מאפשרת ניתוח פתרונות שכלולים כחלק מסביבות מקומיות (כל הגירסאות הנתמכות) ומקוונות.

לקבלת מידע על השימוש בשירות הבודק דרך הקוד של PowerShell, ראה עבודה עם פתרונות באמצעות PowerShell.

הערה

השימוש בבודק של Power Apps אינו מבטיח שייבוא הפתרון יצליח. בדיקות הניתוח הסטטי המתבצעות כנגד הפתרון אינן יודעות את המצב המוגדר של סביבת היעד והצלחת הייבוא עשויה להיות תלויה בפתרונות או תצורות אחרים בסביבה.

גישות חלופיות

לפני שתקרא את הפרטים לגבי יצירת אינטראקציה ברמה הנמוכה ביותר עם ממשקי ה- API של האינטרנט, שקול להשתמש במקום זאת במודול של PowerShell שלנו, Microsoft.PowerApps.Checker.PowerShell זהו כלי נתמך באופן מלא הזמין ב- PowerShell Gallery. ההגבלה הנוכחית היא שהיא דורשת שימוש Windows PowerShell. אם אין לך אפשרות לעמוד בדרישה זו, אינטראקציה ישירה עם ממשקי ה- API היא הגישה הטובה ביותר.

התחלת העבודה

חשוב לציין שניתוח פתרונות עשוי לגרום לתהליך הפעלה ארוך. בדרך כלל, הוא עשוי להימשך שישים (60) שניות עד חמש (5) דקות – תלוי בכמה גורמים, כגון המספר, הגודל והמורכבות של ההתאמות האישיות והקוד. זרימת הניתוח היא רב-שלבית ואסינכרונית, והיא מתחילה בהפעלת משימת ניתוח שכוללת שימוש ב- API של המצב לביצוע שאילתה עבור השלמת העבודה. להלן זרימה לדוגמה עבור ניתוח:

השגת אסימון OAuth
קריאה להעלאה (עבור כל קובץ במקביל)
קריאה לניתוח (הפעלת משימת הניתוח)
קריאה למצב עד לסיום (לולאה עם השהיה בין הקריאות עד לקבלת אות לסיום או עד לעמידה בערכי סף)
הורדת התוצאות מה- URI של SAS שסופק

קיימות כמה וריאציות:

הכללת בדיקת מידע של ערכת הכללים או של הכללים כצעד מקדים. עם זאת, העברת מזהה ערכת כללים בקידוד קשיח או שתצורתו נקבעה תהיה מהירה יותר במעט. מומלץ להשתמש בערכת כללים שעונה על צרכיך.
תוכל לבחור לא להשתמש במנגנון ההעלאה (עיין בהעלאה כדי לראות את המגבלות).

צריך לקבוע את הפרטים הבאים:

איזה מיקום גאוגרפי?
איזו גירסה?
אילו ערכות כללים ואילו כללים?
מהו מזהה הדייר שלך?

עיין במאמרים הבאים כדי לקרוא תיעוד לגבי ממשקי ה- API הבודדים:

אחזור רשימת ערכות הכללים
אחזור רשימת הכללים
העלאת קובץ
הפעלת ניתוח
בדיקת מצב הניתוח

קביעת מיקום גיאוגרפי

כאשר אתה מקיים אינטראקציה Power Apps בודק הקבצים, הקבצים מאוחסנים באופן זמני ב- Azure יחד עם הדוחות שנוצרים. על-ידי שימוש ב- API ספציפי למיקום גיאוגרפי, ניתן לשלוט במיקום אחסון הנתונים. בקשות לנקודת קצה של גיאוגרפיה מנותבות אל מופע אזורי בהתבסס על הביצועים הטובים ביותר (השהיה למבקש). ברגע שהבקשה נכנסת למופע שירות אזורי, כל נתוני העיבוד והנתונים המתמידים נשארים באזור מסוים זה. תגובות 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
ציבור	ייצור	שווייץ	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
ציבור	ייצור	US Government	gov.api.advisor.powerapps.us
ציבור	ייצור	ממשלת ארה"ב L4	high.api.advisor.powerapps.us
ציבור	ייצור	US Government L5 (DOD)‎	mil.api.advisor.appsplatform.us
ציבור	ייצור	מופעל בסין על-ידי 21Vianet	china.api.advisor.powerapps.cn

הערה

ניתן לבחור להשתמש במיקום הגיאוגרפי של Preview כדי לשלב את התכונות והשינויים האחרונים מוקדם יותר. עם זאת, שים לב שתצוגה מקדימה ארצות הברית Azure אזורים בלבד.

ניהול גירסאות

למרות שהוא אינו נדרש, מומלץ לכלול את פרמטר השאילתה api-version עם גירסת ה- API הרצויה. גרסת ה- API הנוכחית היא 2.0 עבור ערכות כללים וכללים ו- 1.0 עבור כל שאר הבקשות. לדוגמה, ערכת הכללים הבא היא בקשת HTTP שמציינת שיש להשתמש ב- API בגירסה 2.0:

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

אם היא לא סופקה, נעשה שימוש בגירסת ה- API האחרונה כברירת מחדל. מומלץ להשתמש במספר גירסה מפורש מכיוון שמספר הגירסה גדל בהפרש קבוע אם יוצגו שינויים משמעותיים. אם מספר הגירסה צוין בבקשה, תישמר תמיכה בתאימות לאחור בגירסאות מתקדמות יותר (שמספרן גבוה יותר).

כללים וערכות כללים

בודק Power Apps דורש רשימת כללים בעת הפעלה. ניתן לספק כללים אלה בצורת כללים בודדים או קיבוץ של כללים, שנקרא ערכת כללים. ערכת כללים מספקת דרך נוחה לציין קבוצת כללים במקום לציין כל כלל בנפרד. לדוגמה, תכונת בודק הפתרונות משתמשת בערכת כללים בשם בודק הפתרונות. בעת הוספה או הסרה של כללים חדשים, השירות כולל שינויים אלה באופן אוטומטי מבלי שיידרש שינוי כלשהו על-ידי היישום הצורך. אם תקבע שרשימת הכללים לא תשתנה באופן אוטומטי כמתואר לעיל, תוכל לציין את הכללים בנפרד. ערכות כללים יכולות לכלול כלל אחד או יותר, ללא הגבלה. כלל כלשהו יכול להימצא בכמה ערכות כללים או באף אחת מהן. ניתן לקבל רשימה של כל ערכות הכללים על-ידי קריאה ל- API באופן הבא: [Geographical URL]/api/ruleset. נקודת הקצה דורשת כעת אימות.

ערכת הכללים של בודק הפתרונות

ערכת הכללים של בודק הפתרונות מכילה קבוצה של כללים בעלי השפעה עם סיכוי מוגבל לתוצאות חיוביות מוטעות. אם אתה מפעיל ניתוח מול פתרון קיים, מומלץ להתחיל עם ערכת כללים זו. זוהי ערכת הכללים שבה נעשה שימוש על-ידי תכונת בודק הפתרונות.

ערכת כללי אישורים של Marketplace

בעת פרסום אפליקציות ב- Marketplace, עליך לקבל אישור עבור האפליקציה שלך. אפליקציות שפורסמו ב- Marketplace נדרשות לעמוד בתקן באיכות גבוהה. ערכת הכללים של האישור Marketplace מכילה את הכללים שהם חלק מקבוצת הכללים של בודק הפתרונות, וכן כללים אחרים כדי להבטיח שרק יישומים באיכות גבוהה יפורסמו במאגר. חלק מכללי האישורים של Marketplace נוטים לתוצאות חיוביות שגויות ועשויים לדרוש תשומת לב רבה יותר לפתרון.

איתור מזהה הדייר שלך

יש צורך במזהה הדייר שלך עבור אינטראקציה עם ממשקי ה- API שדורשים אסימון. עיין במאמר זה לקבלת פרטים לגבי השגת מזהה הדייר. ניתן גם להשתמש בפקודות של PowerShell כדי לאחזר את מזהה הדייר. הדוגמה הבאה משתמשת בפקודות ה- cmdlet ב- AzureAD Module‎.

# Login to Microsoft Entra ID as your user
Connect-AzureAD

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

מזהה הדייר הוא ערך המאפיין ObjectId שמוחזר מ- Get-AzureADTenantDetail. תוכל לראות אותו גם לאחר כניסה באמצעות ה- cmdlet ‏Connect-AzureAD בפלט ה- cmdlet. במקרה זה, השם יהיה TenantId.

אימות והרשאות

שאילתות עבור כללים וערכות כללים לא מחייבות שימוש באסימון OAuth, אך כל שאר ממשקי ה- API מחייבים שימוש באסימון. ממשקי ה- API תומכים בגילוי הרשאות על-ידי קריאה לממשקי ה- API שמחייבים שימוש באסימון. התגובה היא קוד מצב HTTP לא מורשה של 401 עם הכותרת העליונה WWW-Authenticate, ה- URI של ההרשאה ומזהה המשאב. עליך לספק את מזהה הדייר שלך גם בכותרת העליונה של x-ms-tenant-id. עיין במאמר Power Apps אימות ואישור של בודק לקבלת מידע נוסף. זו דוגמה לכותרת העליונה של התגובה שמוחזרת לאחר בקשת API:

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

לקוד העבודה המלא, עיין בדוגמת QuickStart של Web API.

לאחר שתשיג את האסימון, מומלץ לספק את אותו אסימון לקריאות הבאות במחזור החיים של הבקשה. עם זאת, בקשות נוספות עשויות לחייב השגת אסימון חדש מסיבות אבטחה.

אבטחת התעבורה

כדי לספק את ההצפנה הטובה ביותר, שירות הבודק תומך רק בתקשורת שמשתמשת ב- Transport Layer Security (TLS) 1.2 ואילך. לקבלת הדרכה לגבי שיטות עבודה מומלצות עבור .NET TLS, עיין בשיטות העבודה המומלצות של Transport Layer Security (TLS) עם ה- .NET Framework.

תבנית הדוח

התוצאה של ניתוח הפתרון היא קובץ zip שמכיל דוח אחד או יותר בתבנית JSON מתוקננת. תבנית הדוח מבוססת על תוצאות ניתוח סטטי בשם Static Analysis Results Interchange Format ‏(SARIF). קיימים כלים זמינים להצגת מסמכי SARIF ולאינטראקציה איתם. בקר באתר אינטרנט זה לקבלת פרטים. השירות משתמש בגירסה שתיים של תקן OASIS.

למידע נוסף