השתמש בבודק Power Apps עם API של אינטרנט

מאמר
05/01/2024

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

לקבלת מידע על השימוש בשירות הבודק דרך הקוד של 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 המשמש כבסיס
ציבורי	Preview	ארצות הברית	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
ציבורית	ייצור	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

הערה

ניתן לבחור להשתמש במיקום הגיאוגרפי של Preview כדי לשלב את התכונות והשינויים האחרונים מוקדם יותר. עם זאת, שים לב ש- 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. נקודת הקצה דורשת כעת אימות.

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

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

ערכת הכללים לאישור של AppSource

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

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

יש צורך במזהה הדייר שלך עבור אינטראקציה עם ממשקי ה- 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 ספריית האימות (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.

למידע נוסף