Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

OData v4 · Power BI · Excel

En esta página (12)

Feed OData v4 disponible para Power BI, Excel y cualquier cliente OData v4.

ingestia.io expone los marts publicados de tu datalake (datasets *_gold y *_silver) como un feed OData v4 — el formato que Power BI y Excel consumen de forma nativa, sin conector personalizado.

URLQué
https://ingestia.io/api/v1/odataService document (lista las tablas)
https://ingestia.io/api/v1/odata/$metadataEsquema EDMX (tipos de las columnas)
https://ingestia.io/api/v1/odata/<tabela>Filas de una tabla (paginadas)

Esta página es el kit oficial Power BI/Excel — con las recetas listas de conexión, query folding y refresh incremental.

Disponibilidad#

  • Estado: disponible. La disponibilidad sigue el SLA de su plan (99,5% mensual a partir de Growth).
  • Clientes: Power BI (Desktop y Servicio), Excel (Windows y Mac 365), y cualquier cliente OData v4.
  • Región: Brasil (São Paulo).

Permisos#

  • Autenticación por clave de API (consulta Autenticación); solo el dueño del workspace crea/revoca.
  • Exige la acción de exportación de datos (la clave de datos del dueño pasa).
  • La clave ve todos los marts publicados del workspace; las columnas PII nunca salen por la API (ni en el $metadata).

Configuración (Power BI — camino recomendado)#

Inicio → Obtener datos → Consulta en blanco → Editor avanzado:

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" es obligatorio: habla OData v4 y pliega (query folding) filtros/proyecciones hacia el servidor. Camino simple (Excel/PBI): Obtener datos → Fuente OData con …/api/v1/odata?api_key=SUA_CHAVE y autenticación Anónima — recuerda que la clave en la URL se vuelve un secreto.

Query folding — lo que corre en el servidor (pushdown)

Operación en Power QuerySe convierte en
Elegir/quitar columnas$select
Filtrar con = <> > >= < <=$filter (eq/ne/gt/ge/lt/le)
Combinar filtros (Y/O/NO)and/or/not
Contiene / Comienza por / Termina concontains/startswith/endswith
Conservar las primeras N filas$top
Ordenar$orderby
Recuento$count=true

Un filtro que el feed no sabe traducir devuelve HTTP 501 con la lista de lo que se soporta — nunca ignoramos un filtro en silencio (un resultado incorrecto es peor que un error). Simplifica el filtro o aplícalo localmente después.

Refresh incremental (resumen)

Crea los parámetros RangeStart/RangeEnd (tipo Fecha/Hora), filtra la tabla con each [data] >= RangeStart and [data] < RangeEnd y configura la política. El filtro por fecha se pliega hacia el servidor y solo se lee la ventana (menos bytes = menos costo). Receta completa en el kit Power BI/Excel.

Validación (cómo confirmar que funcionó)#

  • GET /api/v1/odata responde 200 con value: [{ name, kind, url }].
  • GET /api/v1/odata/$metadata responde XML EDMX con los tipos de las columnas.
  • En Power BI, el paso de origen carga y el "Editor" muestra los pasos plegados (clic derecho → Ver consulta nativa, cuando esté disponible).

Ejemplo#

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"

Respuesta 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=..."
}

Paginación (server-driven)#

  • Páginas de hasta 1.000 filas con @odata.nextLink — Power BI/Excel siguen el enlace automáticamente hasta el final.
  • Prefer: odata.maxpagesize=N reduce la página (tope 1.000); responde Preference-Applied.
  • Siempre sigue el @odata.nextLink exactamente como lo recibiste (lleva el $skiptoken opaco). Un $skiptoken adulterado responde 400.
  • Profundidad máxima: 1.000.000 de filas por consulta; por encima de eso, 400 indicando filtrar (cada página recorre la tabla completa en el datalake).

Costo#

  • Cobra por los bytes realmente procesados; x-ingestia-cost-brl muestra el valor (una proyección hoy). Cada llamada queda en la auditoría (api.odata.read, con bytes, página y clave) — separable del BI nativo.
  • $count=true ejecuta un COUNT(*) adicional, que también se cuenta.
  • Consejo: apunta el refresh incremental a una columna de partición — el datalake poda particiones y los bytes leídos bajan de verdad.

Seguridad#

  • Solo lectura, con alcance en el workspace (solo marts publicados).
  • Las columnas PII no aparecen en el feed ni en el $metadata.
  • Si la nube propia del cliente se cae, el feed responde 503 — nunca una colección vacía (que haría que Excel leyera "la tabla se vació").

Límites#

  • Subconjunto OData: sin $expand, $apply, $search, $compute, lambdas (any/all) ni aritmética en filtros; texto solo contains/startswith/endswith. Fuera del subconjunto = 501 explícito. $format: solo JSON.
  • Las columnas STRUCT/RECORD no se publican; publica columnas planas.
  • Clave a nivel de workspace (sin recorte por miembro).
  • Cuota: 120 req/min por clave (240/min por workspace), separada del resto de la plataforma — el consumo vía Power BI no degrada el BI nativo. Exceso → 429 con Retry-After.
  • Sin datalake aprovisionado (demo), el feed sirve datos claramente simulados y $filter/$orderby/$count responden 503 — nunca finge que filtró.

Troubleshooting#

SíntomaCausa probableQué hacer
501 en un filtrooperación fuera del subconjuntosimplifica el $filter o filtra localmente
400 $skiptoken inválidoenlace de paginación alteradosigue el @odata.nextLink exactamente
429cuota excedidarespeta el Retry-After; reduce el paralelismo
503 en el feednube propia caída / datalake no aprovisionadointéntalo de nuevo; confirma el aprovisionamiento
Falta una columnaes PII o STRUCTPII no sale por la API; publica columnas planas
Costo altopaginar una tabla grande sin filtrousa refresh incremental en una columna de partición

Próximos pasos: Autenticación · Errores y límites · Troubleshooting.

Enlaces relacionados