Pular para o conteúdo

OData v4 · Power BI · Excel

Nesta página (12)

Feed OData v4 disponível para Power BI, Excel e qualquer cliente OData v4.

O ingestia.io expõe os marts publicados do seu datalake (datasets *_gold e *_silver) como um feed OData v4 — o formato que Power BI e Excel consomem nativamente, sem conector custom.

URLO quê
https://ingestia.io/api/v1/odataService document (lista as tabelas)
https://ingestia.io/api/v1/odata/$metadataSchema EDMX (tipos das colunas)
https://ingestia.io/api/v1/odata/<tabela>Linhas de uma tabela (paginadas)

Esta página é o kit oficial Power BI/Excel — com as receitas prontas de conexão, query folding e refresh incremental.

Disponibilidade#

  • Estado: disponível. A disponibilidade segue o SLA do seu plano (99,5% mensal a partir do Growth).
  • Clientes: Power BI (Desktop e Serviço), Excel (Windows e Mac 365), e qualquer cliente OData v4.
  • Região: Brasil (São Paulo).

Permissões#

  • Autenticação por chave de API (ver Autenticação); só o dono do workspace cria/revoga.
  • Exige a ação de exportação de dados (chave de dados do dono passa).
  • A chave enxerga todos os marts publicados do workspace; colunas PII nunca saem pela API (nem no $metadata).

Configuração (Power BI — caminho recomendado)#

Página Inicial → Obter Dados → Consulta em Branco → Editor Avançado:

m
let
    Chave = "SUA_CHAVE",
    Fonte = OData.Feed("https://ingestia.io/api/v1/odata", null, [
        Headers = [ #"Authorization" = "Bearer " & Chave ],
        Implementation = "2.0"
    ]),
    Tabela = Fonte{[Name = "sua_tabela"]}[Data]
in
    Tabela

Implementation = "2.0" é obrigatório: fala OData v4 e dobra (query folding) filtros/projeções para o servidor. Caminho simples (Excel/PBI): Obter Dados → Feed OData com …/api/v1/odata?api_key=SUA_CHAVE e autenticação Anônima — lembrando que a chave na URL vira segredo.

Query folding — o que roda no servidor (pushdown)

Operação no Power QueryVira
Escolher/remover colunas$select
Filtrar com = <> > >= < <=$filter (eq/ne/gt/ge/lt/le)
Combinar filtros (E/OU/NÃO)and/or/not
Contém / Começa com / Termina comcontains/startswith/endswith
Manter primeiras N linhas$top
Ordenar$orderby
Contagem$count=true

Filtro que o feed não sabe traduzir devolve HTTP 501 com a lista do que é suportado — nunca ignoramos um filtro em silêncio (resultado errado é pior que erro). Simplifique o filtro ou aplique-o localmente depois.

Refresh incremental (resumo)

Crie os parâmetros com os nomes exatos RangeStart e RangeEnd (tipo Data/Hora, em Gerenciar Parâmetros), filtre a tabela por each [data] >= RangeStart and [data] < RangeEnd — >= no início e < no fim, para nenhuma linha entrar duas vezes — e configure a política em Refresh incremental (por exemplo: armazenar 2 anos, atualizar os últimos 7 dias). A coluna usada precisa ser DATE, DATETIME ou TIMESTAMP. O filtro por data dobra para o servidor e só a janela é lida (menos bytes = menos custo); apontar o incremental para a coluna de partição da tabela reduz o byte lido de verdade.

Validação (como confirmar que funcionou)#

  • GET /api/v1/odata responde 200 com value: [{ name, kind, url }].
  • GET /api/v1/odata/$metadata responde XML EDMX com os tipos das colunas.
  • No Power BI, a etapa de fonte carrega e o "Editor" mostra as etapas dobradas (clique direito → Exibir consulta nativa, quando disponível).

Exemplo#

bash
# Service document
curl -H "Authorization: Bearer ing_live_..." https://ingestia.io/api/v1/odata

# Página de uma tabela, com projeção, filtro, contagem e ordenação
curl -H "Authorization: Bearer ing_live_..." \
  "https://ingestia.io/api/v1/odata/silver_vendas?\$select=data,total&\$filter=data ge 2026-01-01&\$orderby=data&\$count=true"

Resposta paginada:

json
{
  "@odata.context": "https://ingestia.io/api/v1/odata/$metadata#silver_vendas",
  "@odata.count": 12345,
  "value": [ /*... */ ],
  "@odata.nextLink": "https://ingestia.io/api/v1/odata/silver_vendas?...$skiptoken=..."
}

Paginação (server-driven)#

  • Páginas de até 1.000 linhas com @odata.nextLink — Power BI/Excel seguem o link automaticamente até o fim.
  • Prefer: odata.maxpagesize=N reduz a página (teto 1.000); responde Preference-Applied.
  • Sempre siga o @odata.nextLink exatamente como recebido (ele carrega o $skiptoken opaco). Um $skiptoken adulterado responde 400.
  • Profundidade máxima: 1.000.000 de linhas por consulta; acima disso, 400 orientando a filtrar (cada página varre a tabela inteira no datalake).

Custo#

  • Cobra pelos bytes realmente processados; x-ingestia-cost-brl mostra o valor (uma projeção hoje). Cada chamada fica na auditoria (api.odata.read, com bytes, página e chave) — separável do BI nativo.
  • $count=true roda um COUNT(*) adicional, também contado.
  • Dica: aponte o refresh incremental para uma coluna de partição — o o datalake poda partições e o byte lido cai de verdade.

Segurança#

  • Somente leitura, escopado ao workspace (marts publicados apenas).
  • Colunas PII não aparecem no feed nem no $metadata.
  • Se a nuvem própria do cliente cair, o feed responde 503 — nunca uma coleção vazia (que faria o Excel ler "a tabela esvaziou").

Limites#

  • Subset OData: sem $expand, $apply, $search, $compute, lambdas (any/all) e aritmética em filtro; texto só contains/startswith/endswith. Fora do subset = 501 explícito. $format: apenas JSON.
  • Colunas STRUCT/RECORD não são publicadas; publique colunas planas.
  • Chave de nível workspace (sem recorte por membro).
  • Quota: 120 req/min por chave (240/min por workspace), separada do resto da plataforma — o consumo via Power BI não degrada o BI nativo. Estouro → 429 com Retry-After.
  • Sem datalake provisionado (demo), o feed serve dados claramente simulados e $filter/$orderby/$count respondem 503 — nunca finge que filtrou.

Troubleshooting#

SintomaCausa provávelO que fazer
501 num filtrooperação fora do subsetsimplifique o $filter ou filtre localmente
400 $skiptoken inválidolink de paginação alteradosiga o @odata.nextLink exatamente
429estouro de quotarespeite o Retry-After; reduza paralelismo
503 no feednuvem própria caída / datalake não provisionadotente de novo; confirme provisionamento
Coluna faltandoé PII ou STRUCTPII não sai pela API; publique colunas planas
Custo altopaginar tabela grande sem filtrouse refresh incremental em coluna de partição

Próximos passos: Autenticação · Erros e limites · Troubleshooting.

Links relacionados