Saltar al contenido

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

Actualizado el 2026-10-04

Tutorial — conectar una API REST genérica

Paso a paso para describir una API REST (URL, ruta de la lista, paginación, token), probar la conexión y cargar los registros como una tabla Bronze.

En esta página (9)

El conector API REST genérica se puede registrar y probar hoy. Lo que está probado por pruebas es nuestro lado — armado de la solicitud, paginación, reanudación, reintento con espera y protección del token. El formato de su API es lo que verifica la prueba de conexión. Ejemplos sintéticos.

Leia antes: Como os dados fluem · Catálogo de conectores.


O que é#

Un conector para sistemas sem conector pronto: usted describe la API (URL base, ruta que lista los registros, dónde está la lista en el JSON y cómo página) y el Ingestia lee los registros según el cronograma y los carga como una tabla en la capa Bronze. Las columnas se descubren en la primera lectura (nombres normalizados a snake_case; objetos y listas se convierten en texto JSON).

Para qué sirve#

Traer datos de un sistema interno, de un proveedor nicho o de una API de socio al datalake, sin esperar un conector dedicado — y sin exportar hojas de cálculo manualmente.

Cuándo usar / cuándo no usar#

  • Use cuando: la API responde JSON por HTTPS, lista registros en un endpoint (GET o POST) y pagina por número de página, por offset o por URL de la siguiente página en el cuerpo (o no pagina).
  • No use cuando: el sistema tiene conector propio en el catálogo (prefiera ese — conoce el sobre y los límites de la API), la API exige OAuth con renovación de token, firma por solicitud o clave en un header propio (esas formas quedan para una evolución del conector), o la respuesta es XML/CSV.

Plano y permisos#

  • Núcleo do produto · verificação de acesso (workspace ativo).
  • A carga passa pela chave de desligamento da capacidade execução de ingestão.
  • Recomendado: un token solo lectura, dedicado al Ingestia.

Pré-requisitos#

  1. La URL base de la API (comienza con https://) y la ruta que lista los registros (ej.: /v1/pedidos).
  2. Saber dónde está la lista en la respuesta: la respuesta ya es un array ([...]), o el array está en una clave (data, results, data.items).
  3. Saber cómo la API pagina y cuál es el tamaño máximo de página aceptado.
  4. Un token Bearer, si la API lo requiere (viaja como Authorization: Bearer …; cifrado, nunca reexpuesto).

Paso a paso#

  1. En el console, vaya a Fontes › Conectores y elija API REST genérica (categoria APIs genéricas).
  2. Complete la descripción de la API:
    • URL base — ej.: https://api.exemplo.com
    • Caminho do recurso — ej.: /v1/pedidos
    • Método HTTP — GET (parámetros en la query) o POST (en el cuerpo JSON)
    • Caminho da lista na resposta — ej.: data (vacío = la respuesta ya es el array)
  3. En Paginação, elija el estilo de la API y complete lo que solicita:
    • Nenhuma — una sola respuesta.
    • Por número de página — parámetro de la página (ej.: page), parámetro de tamaño (ej.: per_page) y el tamaño máximo que la API acepta.
    • Por deslocamento (offset) — parámetro de offset (ej.: offset, skip), parámetro de tamaño (ej.: limit) y el tamaño máximo.
    • URL da próxima página no corpo — dónde la respuesta trae la siguiente URL (ej.: next, links.next, paging.next; acepta URL relativa).
  4. Si la API exige token, pégelo en Token Bearer. En Query extra, fije parámetros que toda llamada debe llevar (ej.: status=active&sort=desc).
  5. Haga clic en Testar conexão. El Ingestia solicita una página pequeña, verifica que la lista existe en la ruta informada y muestra la tabla descubierta.
  6. Con la prueba OK, guarde la fuente e inclúyala en un pipeline. La tabla Bronze se llama registros.

Cómo funciona la lectura (y dónde se detiene)#

  • Por página y por offset, la lectura se detiene en la primera página más corta que el tamaño pedido — por eso el campo solicita el máximo que la API acepta. Si la API ignora el tamaño y devuelve siempre menos, informe el tamaño que realmente devuelve.
  • Por URL en el cuerpo, la lectura sigue la siguiente URL hasta que venga vacía o ausente. Una URL que se repite se trata como fin (no genera loop).
  • Con token vacío, no se envía ningún header de autorización (APIs abiertas).
  • Respuestas 429 y 5xx se reintentan con espera (y Retry-After cuando exista). 401/403 interrumpen con el mensaje "credencial recusada" — el token nunca aparece en el error.
  • La extracción es completa en cada ejecución (sin ventana incremental). Fuentes muy grandes pueden necesitar una ruta más restrictiva o Query extra con filtro.

Problemas comunes#

SintomaCausa provávelO que fazer
"A resposta não tem uma lista em <caminho>"caminho da lista erradoverifique el JSON de la API; use notación con punto (data.items)
Só a primeira página chegaparámetro de tamanho/página errado, ou tamanho maior que o aceitoajuste los nombres de los parámetros y use el máximo real de la API
"Credencial recusada"token inválido, expirado ou sem permissãogenere un token de lectura nuevo y actualice la fuente
Colunas com nomes estranhosa API usa chaves com espaços/acentosnormal — normalizamos para snake_case; renombre en la camada Silver
Objetos aparecem como textocampo aninhadoes el comportamiento esperado (JSON en texto); extraiga en la Silver

Relacionados#

Enlaces relacionados