Meilleures pratiques pour l’API REST Exécuter des requêtes DAX

Suivez ces recommandations pour exploiter pleinement l'API REST Execute DAX Queries dans les charges de travail de production.

Choisir le point de terminaison approprié

Note

L’API Exécuter des requêtes DAX est disponible uniquement pour les modèles sémantiques qui résident sur une capacité de Power BI (Premium, Fabric ou Embedded). Les modèles sémantiques sans attribution de capacité ne sont pas pris en charge.

Power BI propose deux API REST pour l’exécution de requêtes DAX. Choisissez celui qui correspond aux fonctionnalités de votre client :

  • Exécuter des requêtes DAX (flèche) : utilisez chaque fois que votre application cliente peut consommer des flux IPC de flèche binaire. Arrow fournit des charges utiles plus petites, une fidélité de type sans perte et une désérialisation sans copie dans des structures de données colonaires telles que pandas, Polars et Apache Spark. Cette API prend également en charge les paramètres avancés tels que queryTimeout et resultsetRowcountLimit. Nécessite une instance Premium ou Fabric.
  • Execute Queries (JSON) — Utiliser lorsque votre consommateur est une plateforme à code faible/sans code, Power Automate flow ou tout outil qui peut uniquement analyser JSON. Cette API fonctionne sur les capacités Pro, PPU et Premium/Fabric, mais a une limite stricte de 100 000 lignes et 1 000 000 valeurs par requête.

En règle générale, si votre jeu de résultats dépasse quelques centaines de lignes, alimente un pipeline d’analytique ou nécessite une fidélité de type précise, utilisez l’API Exécuter des requêtes DAX avec flèche.

Optimiser les requêtes DAX pour le point de terminaison Arrow

DAX efficace réduit à la fois le temps d’exécution des requêtes et la taille de la charge utile de réponse :

  • Retournez uniquement les colonnes dont vous avez besoin. Utilisez SELECTCOLUMNS ou des listes de colonnes explicites au lieu de retourner des tables entières. Chaque colonne supplémentaire ajoute au schéma et à la taille du lot d’enregistrements.
  • Préférez SUMMARIZECOLUMNS à ADDCOLUMNS avec FILTER. SUMMARIZECOLUMNS produit des plans de requête plus efficaces dans le moteur VertiPaq.
  • Permet TOPN de limiter les lignes. Lorsque vous n'avez besoin que des résultats principaux, TOPN impose la limite au moteur plutôt que de transférer toutes les lignes et de réaliser le filtrage côté client.
  • Évitez les colonnes calculées complexes dans les requêtes. Les mesures et les agrégations sont correctes, mais les calculs au niveau des lignes sur les tables volumineuses peuvent ralentir considérablement l’exécution.
  • Combinez plusieurs EVALUATE instructions dans une seule requête. L’API Exécuter des requêtes DAX prend en charge plusieurs EVALUATE instructions à l’intérieur d’une query chaîne, chacune retournant un jeu de résultats distinct. Cela évite la surcharge des allers-retours HTTP distincts.

Gérer efficacement l’authentification

  • Mettre en cache et réutiliser des jetons. Utilisez le cache de jeton intégré de MSAL pour éviter d'appeler Microsoft Entra ID sur chaque requête. Pour les flux client confidentiels, MSAL met automatiquement en cache les jetons lorsque vous réutilisez la même ConfidentialClientApplication instance.
  • Utilisez des informations d’identification client confidentielles pour les services. Pour les services de niveau intermédiaire sans assistance, utilisez des informations d’identification client (secret client ou certificat) au lieu de jetons d’utilisateur délégués. Cela évite de dépendre d’une session utilisateur connectée.
  • Préférez les identités managées dans Azure. Lorsque votre service s’exécute dans Azure (App Service, Functions, AKS), utilisez une identité managée pour éliminer entièrement la gestion des informations d’identification.
  • Gérez correctement l’expiration du jeton. Les jetons d’accès expirent généralement après une heure. Vérifiez les réponses 401 Unauthorized et rafraîchissez le jeton avant de réessayer.

Gérer les erreurs et les nouvelles tentatives

L’API Exécuter des requêtes DAX peut retourner des erreurs de deux façons :

  1. Erreurs au niveau HTTP : codes d’état HTTP standard avec un corps d’erreur JSON. Codes courants :

    Code de statut Sens Action
    400 Requête incorrecte (DAX non valide, paramètres manquants) Corrigez la demande : ne réessayez pas.
    401 Non autorisé (jeton expiré ou non valide) Actualisez le jeton et réessayez une fois.
    403 Interdit (autorisations insuffisantes) Vérifiez que l’appelant dispose d’autorisations de génération et de lecture sur le modèle sémantique.
    429 Trop de requêtes (limitées) Attendez la durée dans l’en-tête Retry-After, puis réessayez.
    500 / 502 / 503 Erreurs de serveur temporaires Réessayez avec un retrait exponentiel.

  2. Erreurs au niveau du flux : HTTP 200 avec un ensemble de lignes d’erreur incorporé dans la réponse de flèche. Vérifiez les métadonnées du schéma Arrow pour IsError=true, et lisez les valeurs de métadonnées pour FaultCode et FaultString, ainsi que les lignes d'erreur pour obtenir des informations détaillées sur l'emplacement.

Pour les erreurs temporaires, implémentez un backoff exponentiel avec variation aléatoire. Commencez à une seconde, doublez chaque nouvelle tentative et limitez à 30 secondes. Limitez les nouvelles tentatives à trois ou quatre tentatives.

Contrôler la taille du jeu de résultats

Les jeux de résultats volumineux consomment de la mémoire sur la capacité du service et du client appelant. Chaque requête est liée par la limite de mémoire de la capacité.

Pour garder les ensembles de résultats faciles à gérer :

  • Défini resultsetRowcountLimit dans le corps de la requête. Cela applique une limite de lignes côté serveur par jeu de résultats. Si vous savez que votre consommateur n’a besoin que de 10 000 lignes, définissez explicitement la limite.
  • Utiliser TOPN dans votre requête DAX. TOPN limite les lignes au niveau du moteur, ce qui est plus efficace que la troncation côté client.
  • Traiter les lots d’enregistrements de manière incrémentielle. Les réponses Arrow sont divisées en lots d’enregistrements de jusqu’à 100 000 lignes. Dans Python, effectuez une itération sur les lots avec reader.read_next_batch() au lieu d’appeler reader.read_all() lors de l’utilisation de résultats volumineux afin de maintenir la constante d’utilisation de la mémoire.

Sécuriser votre service de niveau intermédiaire

Si vous créez un service de niveau intermédiaire qui proxie des requêtes DAX pour les consommateurs en aval :

  • Valider l’identité de l’appelant. Authentifiez les requêtes entrantes avec Microsoft Entra ID ou un autre fournisseur d’identité avant de transférer des requêtes vers Power BI. N’exposez jamais le point de terminaison pour l'exécution des requêtes DAX en tant que proxy ouvert.
  • Appliquez les privilèges minimum. Accordez au principal de service uniquement les autorisations dont il a besoin (Générer et lire sur des modèles sémantiques spécifiques). N’utilisez pas les rôles d’administrateur d’espace de travail ou d’administrateur de locataire pour l’accès aux API.
  • N’incorporez pas d’informations d’identification dans le code. Stockez les secrets client dans Azure Key Vault ou utilisez des identités managées. Changer les secrets selon une planification régulière.
  • Nettoyer l’entrée DAX. Si votre niveau intermédiaire accepte le texte de requête DAX des appelants, validez l’entrée pour empêcher l’injection d’opérations inattendues.
  • Utilisez le effectiveUsername paramètre avec soin. Ce paramètre applique la sécurité au niveau des lignes au nom d'un utilisateur spécifique. Vérifiez que l’identité appelante est autorisée à se faire passer pour l’utilisateur spécifié.

Superviser et journaliser

Suivez l’intégrité et les performances de votre utilisation de l’API :

  • Métadonnées de requête de journal : enregistrez le texte de la requête, la taille de la réponse, l’état HTTP et la durée de chaque requête. Cela permet d’identifier les requêtes lentes et les pics d’erreurs inattendus.
  • Surveiller les taux de throttling — Suivez les réponses sous forme de pourcentage des demandes totales. Une tendance croissante indique que vous devez réduire la fréquence des demandes ou répartir la charge dans le temps.
  • Mesurez le temps de désérialisation : pour les réponses de flèche, consignez le temps passé à lire et à matérialiser les lots d’enregistrements séparément du temps d’aller-retour HTTP. Cela permet de distinguer la latence réseau du traitement côté client.
  • Use Application Insights ou équivalent : si votre niveau intermédiaire s’exécute dans Azure, activez Application Insights pour obtenir le suivi des dépendances, les alertes d’échec et le suivi distribué de bout en bout.
  • Suivre les taux d’accès au cache de jetons : les taux d’accès au cache faible signifient des appels fréquents d’acquisition de jetons, qui ajoutent une latence et sont un signe de mise en cache MSAL mal configurée.

Contenu connexe

  • Last updated on