Pratiche consigliate per l'API REST Esegui query DAX

Seguire questi consigli per sfruttare al meglio l'API REST Execute DAX Queries durante l'impiego nei carichi di lavoro di produzione.

Scegliere l'endpoint corretto

Power BI offre due API REST per l'esecuzione di query DAX. Scegliere quello che corrisponde alle funzionalità del client:

• Eseguire query DAX (freccia): usare ogni volta che l'applicazione client può usare flussi IPC con freccia binaria. Arrow offre payload più piccoli, fedeltà di tipo senza perdita e deserializzazione a zero copie (zero-copy) in framework a colonne come pandas, Polars e Apache Spark. Questa API supporta anche parametri avanzati come queryTimeout e resultsetRowcountLimit. Richiede capacità Premium o Fabric.
• Execute Queries (JSON): usare quando il consumer è una piattaforma a basso codice o senza codice, Power Automate o qualsiasi strumento in grado di analizzare solo JSON. Questa API funziona sulle capacità Pro, PPU e Premium/Fabric, ma ha un limite rigido di 100.000 righe e 1.000.000 valori per ogni query.

Come regola generale, se il set di risultati supera alcune centinaia di righe, alimenta una pipeline di analisi o richiede una fedeltà del tipo precisa, usare l'API Esegui query DAX con Arrow.

Ottimizzare le query DAX per l'endpoint Arrow

DAX efficiente riduce sia il tempo di esecuzione delle query che le dimensioni del payload della risposta:

• Restituisci solo le colonne di cui hai bisogno. Utilizzare SELECTCOLUMNS o espliciti elenchi di colonne invece di restituire intere tabelle. Ogni colonna aggiuntiva aggiunge allo schema e alle dimensioni del batch di record.
• Preferire SUMMARIZECOLUMNS anziché ADDCOLUMNS con FILTER. SUMMARIZECOLUMNS produce piani di query più efficienti nel motore di VertiPaq.
• Usare TOPN per limitare le righe. Quando sono necessari solo i risultati principali, TOPN impone il limite direttamente nel motore anziché trasferire tutte le righe e filtrare dal lato client.
• Evitare colonne calcolate complesse nelle query. Le misure e le aggregazioni sono appropriate, ma i calcoli a livello di riga in tabelle di grandi dimensioni possono rallentare notevolmente l'esecuzione.
• Combinare più istruzioni EVALUATE in un'unica richiesta. L'API Esegui query DAX supporta più EVALUATE istruzioni all'interno di una query stringa, ognuna delle quali restituisce un set di risultati separato. In questo modo si evita il sovraccarico di round trip HTTP separati.

Gestire l'autenticazione in modo efficiente

• Memorizzare nella cache e riutilizzare i token. Usare la cache dei token predefinita di MSAL per evitare di chiamare Microsoft Entra ID in ogni richiesta. Per i flussi client riservati, MSAL memorizza nella cache automaticamente i token quando si riutilizza la stessa ConfidentialClientApplication istanza.
• Usare le credenziali client riservate per i servizi. Per i servizi non presidiati di livello intermedio, usare le credenziali client (segreto client o certificato) anziché i token utente delegati. In questo modo si evita la dipendenza da una sessione utente con accesso.
• Preferisce le identità gestite in Azure. Quando il servizio viene eseguito in Azure (App Service, Funzioni, Azure Kubernetes Service), usare un'identità gestita per eliminare completamente la gestione delle credenziali.
• Gestire correttamente la scadenza del token. I token di accesso scadono in genere dopo un'ora. Verificare la presenza 401 Unauthorized di risposte e aggiornare il token prima di riprovare.

Gestire errori e ripetizioni

L'API Esegui query DAX può restituire errori in due modi:

1. Errori a livello HTTP : codici di stato HTTP standard con un corpo di errore JSON. Codici comuni:

   Codice di stato	Meaning	Action
   400	Richiesta non valida (DAX non valido, parametri mancanti)	Correggere la richiesta: non riprovare.
   401	Non autorizzato (token scaduto o non valido)	Aggiornare il token e riprovare una volta.
   403	Accesso negato (autorizzazioni insufficienti)	Verificare che il chiamante disponga delle autorizzazioni di compilazione e lettura per il modello semantico.
   429	Troppe richieste (rate limitate)	Attendere la durata nell'intestazione Retry-After , quindi riprovare.
   500 / 502 / 503	Errori temporanei del server	Riprovare con il backoff esponenziale.

2. Errori a livello di flusso : HTTP 200 con un set di righe di errore incorporato nella risposta Arrow. Controllare i metadati dello schema Arrow per IsError=true e leggere i valori dei metadati FaultCode e FaultString, oltre alle righe di errore per ottenere informazioni dettagliate sulla loro posizione.

Per gli errori temporanei, implementare una strategia di backoff esponenziale con jitter. Iniziare da un secondo, raddoppiare ogni tentativo e limitare a 30 secondi. Limita i tentativi a tre o quattro.

Controllare le dimensioni del set di risultati

Set di risultati di grandi dimensioni consumano memoria sia sulla capacità del servizio che sul client chiamante. Ogni richiesta è vincolata dal limite di memoria della capacità.

Per mantenere gestibili i set di risultati:

• Impostare resultsetRowcountLimit nel corpo della richiesta. In questo modo viene applicato un limite di righe lato server per ogni set di risultati. Se sai che il consumer necessita solo di 10.000 righe, imposta il limite in modo esplicito.
• Utilizza TOPN nella query DAX. TOPN limita le righe a livello di motore, che è più efficiente rispetto al troncamento lato client.
• Elaborare i batch di record in modo incrementale. Le risposte con freccia vengono suddivise in batch di record fino a 100.000 righe. In Python eseguire l'iterazione dei batch con reader.read_next_batch() anziché chiamare reader.read_all() quando si lavora con risultati di grandi dimensioni, per mantenere costante l'utilizzo della memoria.

Proteggi il servizio di fascia media

Se costruisci un servizio di livello intermedio che funge da proxy per le query DAX per gli utenti a valle:

• Convalidare l'identità del chiamante. Autenticare le richieste in ingresso con Microsoft Entra ID o un altro provider di identità prima di inoltrare query a Power BI. Non esporre mai l'endpoint "Esegui query DAX" come un proxy aperto.
• Applicare privilegi minimi. Concedere all'entità servizio solo le autorizzazioni necessarie (Compilare e leggere modelli semantici specifici). Non usare ruoli di amministratore dell'area di lavoro o di amministratore tenant per l'accesso alle API.
• Non incorporare le credenziali nel codice. Archiviare i segreti client in Azure Key Vault o usare identità gestite. Ruotare i segreti in base a una pianificazione regolare.
• Purificare l'input DAX. Se il livello intermedio accetta il testo della query DAX dai chiamanti, convalidate l'input per impedire l'inserimento di operazioni inattese.
• Usare il effectiveUsername parametro con attenzione. Questo parametro applica la sicurezza a livello di riga per un utente specifico. Verificare che l'identità chiamante sia autorizzata a rappresentare l'utente specificato.

Monitoraggio e log

Tenere traccia dell'integrità e delle prestazioni dell'utilizzo dell'API:

• Metadati delle query di log : registrare il testo della query, le dimensioni della risposta, lo stato HTTP e la durata per ogni richiesta. Ciò consente di identificare query lente e picchi di errore imprevisti.
• Monitorare le frequenze di limitazione : tenere traccia 429 delle risposte come percentuale delle richieste totali. Una tendenza crescente indica che è necessario ridurre la frequenza delle richieste o distribuire il carico nel tempo.
• Misurare il tempo di deserializzazione — Per le risposte Arrow, registrare il tempo impiegato per la lettura e la materializzazione dei batch di record separatamente dal tempo di round-trip HTTP. Ciò consente di distinguere la latenza di rete dall'elaborazione lato client.
• Usare Application Insights o equivalente : se il livello intermedio viene eseguito in Azure, abilitare Application Insights per ottenere il rilevamento delle dipendenze, gli avvisi degli errori e la traccia distribuita end-to-end.
• Tenere traccia della frequenza di riscontri nella cache dei token : tassi di riscontri nella cache bassa significano chiamate frequenti di acquisizione dei token, che aggiungono latenza e sono un segno di memorizzazione nella cache MSAL non configurata correttamente.

Contenuti correlati

• Informazioni sull'API per l'esecuzione di query DAX
• Inizia con l'API REST Esegui Query DAX
• Esercitazione: Creare un servizio di esecuzione di query DAX di livello intermedio
• Tutorial: estrazione di grandi volumi con Python per data science