Utilizzare l'API Web verifica Power Apps

Articolo
01/25/2024

L'API Web di verifica Power Apps fornisce un meccanismo per eseguire controlli di analisi statica in base a personalizzazioni ed estensioni della piattaforma Microsoft Dataverse. È disponibile per creatori e sviluppatori per eseguire controlli di analisi statica completi delle soluzioni in base a un set di regole di procedure consigliate per individuare rapidamente gli schemi problematici. Il servizio fornisce la logica per la funzione di controllo della soluzionenel portale per creatori di Power Apps ed è incluso come parte dell'automazione per applicazioni inviate ad AppSource. L'interazione diretta con il servizio in questo modo consente di analizzare le soluzioni incluse come parte degli ambienti locali (tutte le versioni supportate) e online.

Per informazioni sull'uso del servizio di verifica dal codice PowerShell, fai riferimento a Utilizzare le soluzioni con PowerShell.

Nota

L'utilizzo di Verifica di Power Apps non garantisce che l'importazione di una soluzione avrà esito positivo. I controlli di analisi statica eseguiti sulla soluzione non conoscono lo stato configurato dell'ambiente di destinazione e il successo dell'importazione può dipendere da altre soluzioni o configurazioni nell'ambiente.

Approcci alternativi

Prima di leggere i dettagli su come interagire a livello inferiore con le API Web, prendi in considerazione la possibilità di usare il nostro modulo PowerShell, Microsoft.PowerApps.Checker.PowerShell. È uno strumento completamente supportato disponibile in PowerShell Gallery. L'attuale limitazione è che richiede Windows PowerShell. Se non sei in grado di soddisfare questo requisito, l'interazione diretta con le API è l'approccio migliore.

Introduzione

È importante tenere presente che un'analisi della soluzione può essere un processo di lunga durata. In genere, possono essere necessari da sessanta (60) secondi a un massimo di cinque (5) minuti, a seconda di una varietà di fattori, quali numero, dimensioni e complessità delle personalizzazioni e del codice. Il flusso di analisi è multiplo e asincrono a partire dall'avvio di un processo di analisi con l'API di stato utilizzata per eseguire query per il completamento del processo. Un flusso di esempio per un'analisi è il seguente:

Recupero di un token OAuth
Caricamento della chiamata (per ogni file in parallelo)
Analisi della chiamata (avvia il processo di analisi)
Stato della chiamata fino al termine (ripetizione ciclica con una pausa tra le chiamate fino alla segnalazione della fine o al raggiungimento delle soglie)
Download dei risultati dall'URI SAS fornito

Alcune varianti sono:

Includi una ricerca del set di regole o delle regole come passaggio preliminare. Tuttavia, sarebbe leggermente più veloce passare un ID di set di regole configurato o codificato. Ti consigliamo di utilizzare un set di regole che soddisfi le tue esigenze.
Puoi scegliere di non utilizzare il meccanismo di caricamento (vedi il caricamento per le limitazioni).

È necessario determinare i seguenti requisiti:

Quale area geografica?
Quale versione?
Quali set di regole e regole?
Qual è l'ID tenant?

Fai riferimento ai seguenti articoli per la documentazione sulle singole API:

Recuperare l'elenco di set di regole
Recuperare l'elenco di regole
Caricare un file
Richiamare l'analisi
Verificare lo stato dell'analisi

Determinare un'area geografica

Quando interagisci con il servizio di verifica Power Apps, i file vengono temporaneamente archiviati in Azure insieme ai report generati. Utilizzando un'API specifica per area geografica puoi controllare dove sono archiviati i dati. Le richieste a un endpoint dell'area geografica vengono instradate a un'istanza regionale in base alle migliori prestazioni (latenza per il richiedente). Una volta che una richiesta entra in un'istanza del servizio regionale, tutti i dati di elaborazione e permanenti rimangono all'interno di quella particolare area. Alcune risposte API restituiranno URL di istanze regionali per le richieste successive una volta che un processo di analisi è stato instradato a un'area specifica. Ogni area geografica può avere una versione diversa del servizio distribuita in un dato momento. L'utilizzo di diverse versioni del servizio è dovuto al processo di distribuzione sicura in più fasi, che garantisce la piena compatibilità delle versioni. Pertanto, la stessa area geografica dovrebbe essere utilizzata per ciascuna chiamata API nel ciclo di vita dell'analisi e potrebbe ridurre il tempo di esecuzione complessivo in quanto i dati non dovranno viaggiare lontano sulla rete. Le aree geografiche disponibili sono:

Data center di Azure	Nome	Geografia	URI di base
Pubblica	Anteprima	Stati Uniti	unitedstatesfirstrelease.api.advisor.powerapps.com
Pubblica	Produzione	Stati Uniti	unitedstates.api.advisor.powerapps.com
Pubblica	Produzione	Europa	europe.api.advisor.powerapps.com
Pubblica	Produzione	Asia	asia.api.advisor.powerapps.com
Pubblica	Produzione	Australia	australia.api.advisor.powerapps.com
Pubblica	Produzione	Giappone	japan.api.advisor.powerapps.com
Pubblica	Produzione	India	india.api.advisor.powerapps.com
Pubblica	Produzione	Canada	canada.api.advisor.powerapps.com
Pubblica	Produzione	Sud America	southamerica.api.advisor.powerapps.com
Pubblica	Produzione	Regno Unito	unitedkingdom.api.advisor.powerapps.com
Pubblica	Produzione	Francia	france.api.advisor.powerapps.com
Public	Produzione	Germania	germany.api.advisor.powerapps.com
Public	Produzione	Emirati Arabi Uniti	unitedarabemirates.api.advisor.powerapps.com
Public	Produzione	Svizzera	switzerland.api.advisor.powerapps.com
Public	Produzione	Sudafrica	southafrica.api.advisor.powerapps.com
Public	Produzione	Corea del Sud	korea.api.advisor.powerapps.com
Public	Produzione	Norvegia	norway.api.advisor.powerapps.com
Public	Produzione	Singapore	singapore.api.advisor.powerapps.com
Public	Produzione	US Government	gov.api.advisor.powerapps.us
Pubblica	Produzione	Governo degli Stati Uniti L4	high.api.advisor.powerapps.us
Pubblica	Produzione	Governo degli Stati Uniti L5 (DOD)	mil.api.advisor.appsplatform.us
Pubblica	Produzione	Cina gestito da 21Vianet	china.api.advisor.powerapps.cn

Nota

Puoi scegliere di utilizzare l'area geografica di anteprima per incorporare le funzionalità e le modifiche più recenti in precedenza. Tuttavia, l'anteprima utilizza solo le aree di Azure degli Stati Uniti.

Controllo delle versioni

Sebbene non richiesto, ti consigliamo di includere il parametro della stringa di query api-version con la versione dell'API desiderata. La versione API corrente è 2.0 per set di regole e regole e 1.0 per tutte le altre richieste. Ad esempio, il seguente set di regole è una richiesta HTTP che specifica di utilizzare la versione API 2.0:

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

Se non fornita, verrà utilizzata per impostazione predefinita l'ultima versione dell'API. Ti consigliamo di utilizzare un numero di versione esplicito poiché la versione verrà incrementata se vengono introdotte modifiche che causano un'interruzione. Se il numero di versione viene specificato in una richiesta, verrà mantenuto il supporto di compatibilità con le versioni precedenti nelle versioni successive (numericamente superiori).

Set di regole e regole

Verifica Power Apps richiede un elenco di regole quando viene eseguito. Queste regole possono essere fornite sotto forma di regole individuali o di un raggruppamento di regole, indicato come set di regole. Un set di regole è un modo conveniente per specificare un gruppo di regole invece di dover specificare ciascuna regola singolarmente. Ad esempio, la funzione di controllo della soluzione utilizza un set di regole denominato Verifica soluzione. Quando vengono aggiunte o rimosse nuove regole, il servizio includerà automaticamente queste modifiche senza richiedere alcuna modifica da parte dell'applicazione che utilizza. Se l'elenco delle regole non deve cambiare automaticamente come descritto sopra, puoi specificare le regole singolarmente. I set di regole possono avere una o più regole senza limiti. Una regola può trovarsi in nessuno o in più set di regole. Puoi ottenere un elenco di tutti i set di regole chiamando l'API come segue: [Geographical URL]/api/ruleset. L'endpoint ora richiede l'autenticazione.

Set di regole della verifica della soluzione

Il set di regole per il controllo della soluzione contiene una serie di regole di impatto che hanno possibilità limitate di falsi positivi. Se si esegue l'analisi su una soluzione esistente, ti consigliamo di iniziare con questo set di regole. Questo è il set di regole utilizzato dalla funzionalità di controllo della soluzione.

Set di regole di certificazione AppSource

Quando si pubblicano applicazioni in AppSource è necessario ottenere la certificazione dell'applicazione. Le applicazioni pubblicate in AppSource devono soddisfare uno standard di alta qualità. Il set di regole di certificazione AppSource contiene le regole che fanno parte del set di regole della verifica della soluzione, oltre a regole aggiuntive per garantire che nell'archivio siano pubblicate solo applicazioni di alta qualità. Alcune delle regole di certificazione AppSource sono più inclini a falsi positivi e possono richiedere un'ulteriore attenzione per la risoluzione.

Trovare l'ID tenant

L'ID del tenant è necessario per interagire con le API che richiedono un token. Fai riferimento a questo articolo per i dettagli su come ottenere l'ID tenant. PUoi inoltre utilizzare i comandi di PowerShell per recuperare l'ID tenant. L'esempio seguente applica i cmdlet nel modulo AzureAD.

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

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

L'ID tenant è il valore della proprietà ObjectId da cui viene restituito Get-AzureADTenantDetail. Potresti anche vederlo dopo aver effettuato l'accesso usando il cmdlet Connect-AzureAD nell'output del cmdlet. In questo caso verrà denominato TenantId.

Autenticazione e autorizzazione

Le query per regole e set di regole non richiedono un token OAuth, ma tutte le altre API richiedono il token. Le API supportano il rilevamento delle autorizzazioni chiamando una delle API che richiedono un token. La risposta sarà il codice di stato HTTP non autorizzato 401 con un'intestazione WWW-Authenticate, l'URI di autorizzazione e l'ID risorsa. Devi fornire il tuo ID tenant anche nell'intestazione x-ms-tenant-id. Fai riferimento a Autenticazione e autorizzazione di Verifica Power Apps per maggiori informazioni. Di seguito è riportato un esempio dell'intestazione della risposta restituita da una richiesta API:

WWW-Authenticate →Bearer authorization_uri="https://login.microsoftonline.com/0082fff7-33c5-44c9-920c-c2009943fd1e", resource_id="https://api.advisor.powerapps.com/"

Una volta che hai queste informazioni, puoi scegliere di usare la libreria di autenticazione Microsoft Authentication Library (MSAL) o qualche altro meccanismo per acquisire il token. Di seguito è riportato un esempio di come eseguire questa operazione utilizzando C# e la raccolta 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();

Per il codice operativo completo, consulta l'API Web esempio di Avvio rapido.

Dopo aver acquisito il token, ti consigliamo di fornire lo stesso token alle chiamate successive nel ciclo di vita della richiesta. Tuttavia, le richieste aggiuntive garantiranno probabilmente l'acquisizione di un nuovo token per motivi di sicurezza.

Sicurezza dei trasporti

Per la migliore crittografia, il servizio di verifica supporta solo le comunicazioni che utilizzano Transport Layer Security (TLS) 1.2 e versioni successive. Per indicazioni sulle procedure consigliate di .NET relative a TLS, consulta Procedure consigliate per Transport Layer Security (TLS) con .NET Framework.

Formato dei report

Il risultato dell'analisi della soluzione è un file zip contenente uno o più report in un formato JSON standardizzato. Il formato del report si basa sui risultati dell'analisi statica denominato SARIF (Static Analysis Results Interchange Format). Sono disponibili strumenti per visualizzare e interagire con i documenti SARIF. Fai riferimento a questo sito Web per i dettagli. Il servizio usa la versione due dello standard OASIS.

Vedi anche