Boas práticas para a API REST Execute DAX Queries

Siga estas recomendações para tirar o máximo proveito da API REST Execute DAX Queries em cargas de trabalho de produção.

Escolha o ponto final certo

O Power BI oferece duas APIs REST para execução de consultas DAX. Escolha aquele que corresponda às capacidades do seu cliente:

• Executar Consultas DAX (Arrow) — Use sempre que a aplicação cliente possa consumir fluxos binários Arrow IPC. A Arrow fornece cargas úteis menores, alta fidelidade de tipos sem perdas e desserialização sem cópia em frameworks colunares como pandas, Polars e Apache Spark. Esta API também suporta parâmetros avançados como queryTimeout e resultsetRowcountLimit. Requer capacidade Premium ou Fabric.
• Executar Consultas (JSON) — Use quando o seu consumidor é uma plataforma low-code/no-code, um fluxo do Power Automate, ou qualquer ferramenta que só consiga interpretar JSON. Esta API funciona em capacidades Pro, PPU e Premium/Fabric, mas tem um limite rígido de 100.000 linhas e 1.000.000 de valores por consulta.

Como regra geral, se o seu conjunto de resultados ultrapassar algumas centenas de linhas, alimentar um pipeline de análise ou exigir fidelidade precisa dos tipos, use a API Execute DAX Queries com Arrow.

Otimizar consultas de DAX para o endpoint Arrow

Um DAX eficiente reduz tanto o tempo de execução da consulta como o tamanho da carga útil de resposta:

• Devolve apenas as colunas de que precisares. Use SELECTCOLUMNS ou listas de colunas explícitas em vez de devolver tabelas inteiras. Cada coluna extra aumenta o esquema e o tamanho do lote de registos.
• Prefira SUMMARIZECOLUMNS em vez de ADDCOLUMNS com FILTER. SUMMARIZECOLUMNS produz planos de consulta mais eficientes no motor VertiPaq.
• Use TOPN para limitar as linhas. Quando só precisas dos melhores resultados, TOPN empurra o limite para o motor em vez de transferir todas as linhas e filtrar do lado do cliente.
• Evite colunas calculadas complexas nas consultas. Medidas e agregações são adequadas, mas cálculos ao nível das linhas em tabelas grandes podem atrasar significativamente a execução.
• Combine várias EVALUATE instruções num único pedido. A API Execute DAX Queries suporta múltiplas EVALUATE instruções dentro de uma única query string, cada uma devolvendo um conjunto de resultados separado. Isto evita a sobrecarga de viagens HTTP separadas de ida e volta.

Gerir a autenticação de forma eficiente

• Cache e reutiliza fichas. Use a cache de tokens incorporada da MSAL para evitar chamar o Microsoft Entra ID em cada pedido. Para fluxos de clientes confidenciais, o MSAL armazena tokens automaticamente em cache quando reutiliza a mesma ConfidentialClientApplication instância.
• Use credenciais confidenciais de clientes para serviços. Para serviços intermédios não acompanhados, utilize credenciais do cliente (secreto do cliente ou certificado) em vez de tokens de utilizador delegados. Isto evita a dependência de uma sessão de utilizador ativa.
• Prefiro identidades geridas no Azure. Quando o seu serviço é executado no Azure (App Service, Functions, AKS), use uma identidade gerida para eliminar completamente a gestão de credenciais.
• Lide com a expiração dos tokens de forma elegante. Os tokens de acesso normalmente expiram após uma hora. Verifique as 401 Unauthorized respostas e atualize o token antes de tentar novamente.

Lidar com erros e tentativas repetidas

A API Execute DAX Queries pode devolver erros de duas formas:

1. Erros ao nível HTTP — Códigos de estado HTTP padrão com corpo de erro JSON. Códigos comuns:

   Código de estado	Meaning	Ação
   400	Pedido inválido (DAX inválido, parâmetros em falta)	Corrige o pedido — não tente novamente.
   401	Não autorizado (token expirado ou inválido)	Atualiza o token e tenta novamente uma vez.
   403	Proibido (permissões insuficientes)	Verifique se o chamador tem permissões de Build e Read no modelo semântico.
   429	Pedidos a mais (limitado)	Espera pela duração no Retry-After cabeçalho e depois tenta novamente.
   500 / 502 / 503	Erros transitórios de servidor	Tenta novamente com recuo exponencial.

2. Erros ao nível do fluxo — HTTP 200 com um conjunto de linhas de erro embutido na resposta Arrow. Verifique os metadados do esquema Arrow para IsError=true e leia os valores dos metadados FaultCode além das linhas de erro para informações detalhadas sobre a localização.

Para erros transitórios, implemente o backoff exponencial com jitter. Comece com um segundo, dobre em cada tentativa e limite aos 30 segundos. Limite as tentativas para três ou quatro.

Controlar o tamanho do conjunto de resultados

Grandes conjuntos de resultados consomem memória tanto na capacidade do serviço como no cliente chamador. Cada pedido está limitado pelo limite de memória da capacidade.

Para manter os conjuntos de resultados geríveis:

• Defina resultsetRowcountLimit no corpo da requisição. Isto impõe um limite de linhas do lado do servidor por conjunto de resultados. Se souber que o seu consumidor só precisa de 10.000 linhas, defina o limite explicitamente.
• Use TOPN na sua consulta DAX. TOPN limita as linhas ao nível do motor, o que é mais eficiente do que truncar o lado do cliente.
• Processo regista os lotes de forma incremental. As respostas do Arrow são divididas em lotes de registros de até 100.000 linhas. Em Python, itera em lotes com reader.read_next_batch() em vez de chamar reader.read_all() quando trabalhas com resultados grandes, para manter o uso de memória constante.

Garanta o seu serviço de nível médio

Se construir um serviço de nível médio que funcione como proxy para consultas DAX para os consumidores finais:

• Validar a identidade do chamador. Autentique os pedidos recebidos com o Microsoft Entra ID ou outro fornecedor de identidade antes de encaminhar as consultas para o Power BI. Nunca exponha o endpoint de execução de consultas DAX como um proxy aberto.
• Impor o princípio do menor privilégio. Conceda ao principal do serviço apenas as permissões de que necessita (Build e Read em modelos semânticos específicos). Não uses funções de administrador de espaço de trabalho ou administrador de tenant para acesso à API.
• Não incorpores credenciais no código. Armazene os segredos dos clientes no Azure Key Vault ou use identidades geridas. Alterna os segredos num horário regular.
• Sanitizar a entrada DAX. Se o seu intermediário aceitar texto de consulta DAX dos chamadores, valide a entrada para evitar a injeção de operações inesperadas.
• Use o effectiveUsername parâmetro com cuidado. Este parâmetro aplica Segurança ao Nível da Linha para um utilizador específico. Certifique-se de que a identidade que chama está autorizada a fazer-se passar pelo utilizador especificado.

Monitorizar e registar

Acompanhe a saúde e o desempenho da utilização da sua API:

• Metadados da consulta de registo — Registar o texto da consulta, o tamanho da resposta, o estado HTTP e a duração de cada pedido. Isto ajuda a identificar consultas lentas e picos de erro inesperados.
• Monitorize as taxas de redução de potência — Acompanhe 429 as respostas como percentagem do total de pedidos. Uma tendência ascendente indica que precisa de reduzir a frequência dos pedidos ou distribuir a carga ao longo do tempo.
• Meça o tempo de desserialização — Para respostas Arrow, regista o tempo gasto a ler e materializar lotes de registos separadamente do tempo de ida e volta do HTTP. Isto ajuda a distinguir a latência da rede do processamento do lado do cliente.
• Use Application Insights ou equivalente — Se a sua camada intermédia estiver alojada em Azure, ative o Application Insights para obter rastreamento de dependências, alertas de falhas e rastreamento distribuído de ponta a ponta.
• Monitorize as taxas de acerto da cache de tokens — Taxas baixas de acerto na cache indicam chamadas frequentes para a aquisição de tokens, o que acrescenta latência e é um sinal de configuração incorreta da cache MSAL.

Conteúdo relacionado

• Compreenda a API de Execução de Consultas DAX
• Comece com a API REST Execute DAX Queries
• Tutorial: Construa um serviço de execução de consultas DAX de nível intermédio
• Tutorial: Extração de Python de alto volume para ciência de dados