Χρήση του API Web του ελέγχου του Power Apps

Άρθρο
01/25/2024

Το Web API του ελέγχου του Power Apps παρέχει έναν μηχανισμό για την εκτέλεση ελέγχων στατικής ανάλυσης σε σχέση με προσαρμογές και επεκτάσεις στην πλατφόρμα Microsoft Dataverse. Είναι διαθέσιμο για να πραγματοποιούν οι δημιουργοί και οι προγραμματιστές εμπλουτισμένους ελέγχους στατικής ανάλυσης στις λύσεις τους σε σχέση με ένα σύνολο κανόνων βέλτιστων πρακτικών και να εντοπίζουν γρήγορα προβληματικά μοτίβα. Η υπηρεσία παρέχει τη λογική για τη δυνατότητα ελεγκτή λύσης στην πύλη του κατασκευαστή Power Apps και περιλαμβάνεται ως μέρος της αυτοματοποίησης για τις εφαρμογές που υποβάλλονται στο AppSource. Η απευθείας αλληλεπίδραση με την υπηρεσία με αυτόν τον τρόπο επιτρέπει την ανάλυση των λύσεων που περιλαμβάνονται ως μέρος του περιβάλλοντος εσωτερικής εγκατάστασης (όλες οι υποστηριζόμενες εκδόσεις) και των ηλεκτρονικών περιβαλλόντων.

Για πληροφορίες σχετικά με τη χρήση της υπηρεσίας ελεγκτή από τον κώδικα PowerShell, ανατρέξτε στην ενότητα Εργασία με λύσεις με χρήση του PowerShell.

Σημείωμα

Η χρήση του ελεγκτή Power Apps δεν εγγυάται ότι μια εισαγωγή λύσης θα είναι επιτυχής. Οι στατικοί έλεγχοι ανάλυσης που εκτελούνται σε σχέση με τη λύση δεν γνωρίζουν τη ρυθμισμένη κατάσταση του περιβάλλοντος προορισμού και η επιτυχία της εισαγωγής μπορεί να εξαρτάται από άλλες λύσεις ή ρυθμίσεις παραμέτρων στο περιβάλλον.

Εναλλακτικές προσεγγίσεις

Πριν να διαβάσετε τις λεπτομέρειες σχετικά με τον τρόπο αλληλεπίδρασης στο χαμηλότερο επίπεδο με τα API Web, εξετάστε το ενδεχόμενο να αξιοποιείτε αντ' αυτής τη λειτουργική μονάδα PowerShell, τη Microsoft.PowerApps.Checker.PowerShell. Πρόκειται για ένα πλήρως υποστηριζόμενο εργαλείο που είναι διαθέσιμο στη Συλλογή PowerShell. Ο τρέχων περιορισμός είναι ότι απαιτεί το 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
Δημόσιος	Παραγωγή	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

Σημείωμα

Μπορείτε να επιλέξετε να χρησιμοποιήσετε τη γεωγραφία προεπισκόπησης για να ενσωματώσετε νωρίτερα τις πιο πρόσφατες δυνατότητες και αλλαγές. Ωστόσο, λάβετε υπόψη σας ότι η προεπισκόπηση χρησιμοποιεί μόνο τις περιοχές Azure στις Ηνωμένες Πολιτείες.

Έκδοση

Παρόλο που δεν απαιτείται, συνιστάται η συμπερίληψη της παραμέτρου ερωτήματος έκδοσης API (api-version) με την επιθυμητή έκδοση API. Η τρέχουσα έκδοση API είναι 2.0 για σύνολα κανόνων και κανόνες και 1.0 για όλες τις άλλες αιτήσεις. Για παράδειγμα, το ακόλουθο σύνολο κανόνων είναι ένα αίτημα HTTP που καθορίζει τη χρήση της έκδοσης 2.0 του API:

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.

# 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 του API Web.

Αφού αποκτήσετε το διακριτικό, συνιστάται να παρέχετε το ίδιο διακριτικό για τις μεταγενέστερες κλήσεις στον κύκλο ζωής της αίτησης. Ωστόσο, περισσότερες αιτήσεις είναι πιθανό να επιβάλλουν την απόκτηση ενός νέου διακριτικού για λόγους ασφαλείας.

Ασφάλεια μεταφοράς

Για την καλύτερη δυνατή κρυπτογράφηση, η υπηρεσία ελεγκτή υποστηρίζει μόνο επικοινωνίες με χρήση ασφάλειας Transport Layer Security (TLS) 1.2 και άνω. Για καθοδήγηση σχετικά με τις βέλτιστες πρακτικές του .NET γύρω από το TLS, ανατρέξτε στις βέλτιστες πρακτικές για Transport Layer Security (TLS) με το .NET Framework.

Μορφή αναφοράς

Το αποτέλεσμα της ανάλυσης λύσεων είναι ένα αρχείο zip που περιέχει μία ή περισσότερες αναφορές σε τυποποιημένη μορφή JSON. Η μορφή αναφοράς βασίζεται σε στατικά αποτελέσματα ανάλυσης, τα οποία αναφέρονται ως Static Analysis Results Interchange Format (SARIF). Υπάρχουν διαθέσιμα εργαλεία για την προβολή και την αλληλεπίδραση με έγγραφα SARIF. Για λεπτομέρειες ανατρέξτε σε αυτήν την τοποθεσία web. Η υπηρεσία χρησιμοποιεί την έκδοση δύο του προτύπου OASIS.