Práticas recomendadas para a API REST Execute DAX Queries

Siga estas recomendações para aproveitar ao máximo a API REST de execução de consultas DAX em cargas de trabalho de produção.

Escolha o ponto de extremidade certo

Note

A API Executar Consultas DAX está disponível apenas para modelos semânticos que residem em uma capacidade do Power BI (Premium, Fabric ou Embedded). Não há suporte para modelos semânticos sem uma atribuição de capacidade.

Power BI oferece duas APIs REST para executar consultas DAX. Escolha aquele que corresponda aos recursos do cliente:

  • Executar consultas DAX (Arrow) – use sempre que seu aplicativo cliente puder consumir fluxos IPC binários Arrow. Arrow oferece cargas menores, fidelidade de tipos sem perdas e desserialização sem cópia em estruturas colunais como pandas, Polars e Apache Spark. Essa API também dá suporte a parâmetros avançados como queryTimeout e resultsetRowcountLimit. Requer capacidade Premium ou Fabric.
  • Execute Queries (JSON) — Use quando o consumidor for uma plataforma low-code/no-code, fluxo do Power Automate ou qualquer ferramenta que só possa interpretar JSON. Essa API funciona em capacidades Pro, PPU e Premium/Fabric, mas tem um limite rígido de 100.000 linhas e 1.000.000 valores por consulta.

Como regra geral, se o conjunto de resultados exceder algumas centenas de linhas, for processado em um pipeline de análise ou exigir fidelidade de tipos precisa, use a API Execute Consultas DAX com Arrow.

Otimizar consultas DAX para o endpoint Arrow

O DAX eficiente reduz o tempo de execução da consulta e o tamanho da carga de resposta:

  • Retorne somente as colunas de que você precisa. Use SELECTCOLUMNS ou explicite listas de colunas em vez de retornar tabelas inteiras. Cada coluna extra aumenta o esquema e o tamanho do lote de registros.
  • Prefira SUMMARIZECOLUMNS em vez de ADDCOLUMNS com FILTER. SUMMARIZECOLUMNS produz planos de consulta mais eficientes no mecanismo VertiPaq.
  • Use TOPN para limitar linhas. Quando você só precisa dos principais resultados, TOPN transfere o limite para o mecanismo em vez de transferir todas as linhas e filtrar no cliente.
  • Evite colunas calculadas complexas em consultas. Medidas e agregações são boas, mas cálculos em nível de linha em tabelas grandes podem reduzir significativamente a execução.
  • Combine várias EVALUATE declarações em uma única solicitação. A API de Execução de Consultas DAX oferece suporte a várias instruções EVALUATE em uma cadeia de caracteres query, cada uma retornando um conjunto de resultados distinto. Isso evita a sobrecarga de viagens de ida e volta HTTP separadas.

Gerenciar a autenticação com eficiência

  • Armazenar em cache e reutilizar tokens. Use o cache de token interno da MSAL para evitar chamar Microsoft Entra ID em cada solicitação. Para fluxos de cliente confidenciais, a MSAL armazena tokens em cache automaticamente quando você reutiliza a mesma ConfidentialClientApplication instância.
  • Use credenciais de cliente confidenciais para serviços. Para serviços autônomos de camada intermediária, use credenciais de cliente (segredo do cliente ou certificado) em vez de tokens de usuário delegados. Isso evita a dependência de uma sessão de usuário autenticada.
  • Prefira identidades gerenciadas em Azure. Quando o serviço for executado em Azure (Serviço de Aplicativo, Funções, AKS), use uma identidade gerenciada para eliminar totalmente o gerenciamento de credenciais.
  • Trate a expiração do token de forma adequada. Os tokens de acesso normalmente expiram após uma hora. Verifique se há 401 Unauthorized respostas e atualize o token antes de tentar novamente.

Manipular erros e novas tentativas

A API executar consultas DAX pode retornar erros de duas maneiras:

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

    Código de status Meaning Ação
    400 Solicitação incorreta (DAX inválido, parâmetros ausentes) Corrija a solicitação – não tente novamente.
    401 Não autorizado (token expirado ou inválido) Atualize o token e tente novamente uma vez.
    403 Proibido (permissões insuficientes) Verifique se o chamador tem permissões de Compilação e Leitura no modelo semântico.
    429 Muitas solicitações (limitadas) Aguarde a duração no Retry-After cabeçalho e tente novamente.
    500 / 502 / 503 Erros transitórios do servidor Repita com um recuo exponencial.

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

Para erros transitórios, implemente o recuo exponencial com jitter. Comece em um segundo, dobre em cada repetição e limite em 30 segundos. Limite novas tentativas a três ou quatro tentativas.

Controlar o tamanho do conjunto de resultados

Grandes conjuntos de resultados consomem memória tanto na capacidade no serviço quanto no cliente que está realizando a chamada. Cada solicitação é restrita pelo limite de memória da capacidade disponível.

Para manter os conjuntos de resultados gerenciáveis:

  • Defina resultsetRowcountLimit no corpo da solicitação. Isso impõe uma limitação de linhas no lado do servidor por conjunto de resultados. Se você souber que seu consumidor precisa apenas de 10.000 linhas, defina o limite explicitamente.
  • Use TOPN em sua consulta DAX. TOPN limita linhas no nível do mecanismo, o que é mais eficiente do que truncar no lado do cliente.
  • Processar lotes de registro incrementalmente. As respostas Arrow são divididas em lotes de registros de até 100.000 linhas. Em Python, ao trabalhar com resultados grandes, itere em lotes com reader.read_next_batch() em vez de chamar reader.read_all() para manter o uso de memória constante.

Proteja seu serviço intermediário

Se você criar um serviço de camada intermediária que intermedie consultas DAX para consumidores a jusante:

  • Validar a identidade do chamador. Autentique solicitações de entrada com Microsoft Entra ID ou outro provedor de identidade antes de encaminhar consultas para Power BI. Nunca exponha o endpoint de Execução de Consultas DAX como um proxy aberto.
  • Impor privilégios mínimos. Conceda à entidade de serviço apenas as permissões necessárias (compilar e ler modelos semânticos específicos). Não use funções de administrador de workspace ou administrador de locatários para acesso à API.
  • Não insira credenciais no código. Armazene segredos do cliente em Azure Key Vault ou use identidades gerenciadas. Girar segredos em um agendamento regular.
  • Sanitize a entrada do DAX. Se a camada intermediária aceitar o 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. Esse parâmetro aplica Row-Level Security em nome de um usuário específico. Verifique se a identidade de chamada está autorizada a representar o usuário especificado.

Monitorar e registrar em log

Acompanhe a integridade e o desempenho do uso da API:

  • Metadados de consulta de log — registre o texto da consulta, o tamanho da resposta, o status HTTP e a duração de cada solicitação. Isso ajuda a identificar consultas lentas e picos de erro inesperados.
  • Monitorar taxas de limitação — Acompanhar 429 respostas como um percentual do total de solicitações. Uma tendência crescente indica que você precisa reduzir a frequência da solicitação ou espalhar a carga ao longo do tempo.
  • Medir o tempo de desserialização – para respostas do Arrow, registre o tempo gasto lendo e materializando lotes de registro separadamente do tempo de ida e volta do HTTP. Isso ajuda a distinguir a latência de rede do processamento do lado do cliente.
  • Use o Application Insights ou equivalente — se a camada intermediária for executada em Azure, habilite o Application Insights para obter controle de dependência, alertas de falha e rastreamento distribuído de ponta a ponta.
  • Controlar as taxas de ocorrência do cache de token – taxas de ocorrência de cache baixas significam chamadas frequentes de aquisição de token, que adicionam latência e são um sinal de cache MSAL configurado incorretamente.

Conteúdo relacionado

  • Last updated on