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

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

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

הערה

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

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

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

תחילת העבודה

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

  1. השגת אסימון OAuth
  2. קריאה להעלאה (עבור כל קובץ במקביל)
  3. קריאה לניתוח (הפעלת משימת הניתוח)
  4. קריאה למצב עד לסיום (לולאה עם השהיה בין הקריאות עד לקבלת אות לסיום או עד לעמידה בערכי סף)
  5. הורדת התוצאות מה- 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
ציבורית ייצור 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 הנוכחית היא 1.0. לדוגמה, להלן בקשת HTTP של ערכת כללים שמציינת שיש להשתמש ב- API בגירסה 1.0:

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

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

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

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

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

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

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

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

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

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

# Login to AAD 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/"

לאחר שמידע זה יהיה ברשותך, תוכל לבחור להשתמש ב- Azure Active Directory Authentication Library‏ (ADAL) או במנגנון אחר להשגת האסימון. להלן דוגמה לביצוע פעולה זו באמצעות 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}");
        }
    }
}

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

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

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

תבנית הדוח

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

למידע נוסף

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