Orígenes de datos desde servicios web REST/json

Orígenes de datos desde servicios web REST/json

Resumen

El conector a servicios web REST/JSON permite recolectar datos desde un servicio web, o configurar acciones de escritura sobre él, para luego crear vistas de datos y exponerlos en métodos de su API. En esta guía configura la solicitud al servicio y el procesamiento de su respuesta, hasta guardar el origen de datos.

Antes de comenzar

  • Tenga a mano la URL del servicio, el tipo de solicitud que espera, sus credenciales si está protegido y la forma de la respuesta JSON: en qué atributo vienen los registros.

La solicitud

Vaya a Orígenes de datos > Desde servicio web > REST/JSON. La pantalla de la solicitud reúne todo lo que se envía al servicio.

URL y tipo de solicitud

Ingrese la URL del servicio, por ejemplo https://api.example.com/accounts/v1/invoices?year=2022. Seleccione el tipo de solicitud (GET, POST, PUT, PATCH o DELETE) según lo indique la documentación del servicio.

Selección del método de la solicitud Nombre y valor por defecto del parámetro de la URL

En Acciones de lectura o escritura deje Lectura, salvo que la solicitud modifique datos en el origen; así evita escrituras no deseadas.

Probar

Haga clic en Probar. Debajo se muestra el código de estado de la respuesta (por ejemplo 200), sus cabeceras y el cuerpo recibido.

La respuesta muestra el código de estado que devolvió el origen. El método responde con su propio código salvo que active Trasladar el código HTTP de respuesta del origen de datos en el método (ver Plantillas Jinja para códigos de respuesta HTTP).

Mapeos

Un mapeo vuelve variable una parte de la URL, para exponerla como parámetro del método de la API o relacionarla con una variable de contexto. Haga clic en Mapear orígen, ingrese un nombre de mapeo (será el nombre del parámetro) y un valor por defecto, y confirme. Luego escriba el nombre entre llaves dobles en la posición que corresponda: /users/{{userId}} o ?q={{texto}}. Puede agregar varios mapeos sobre una misma URL.

Parámetros, cabeceras y cuerpo

  • Parámetros: pares de nombre y valor. Sin un tipo de contenido seleccionado se envían en la query-string (?anio=1999&mes=12). Con El valor será editable, el parámetro queda editable en la vista de datos y en los métodos de la API.
  • Cabeceras: las cabeceras HTTP que el servicio requiera. Por defecto no son editables; puede marcarlas como editables o aplicar mapeos sobre parte de su valor para exponerlas en el método.
  • Cuerpo de la solicitud: seleccione el Content-Type. Con application/json se habilita el cuerpo, donde pega el JSON que espera el servicio y usa mapeos entre llaves dobles para los valores editables. Con application/x-www-form-urlencoded o multipart/form-data, los valores van en la pestaña Parámetros.
Cabeceras expuestas como parámetros del método Tipo de contenido del cuerpo de la solicitud Pestaña Cabeceras con una cabecera agregada a la solicitud
No ingrese parámetros ni cabeceras editables que contengan tokens o claves de acceso al servicio web.

Tipo de cuerpo enviado

En Cuerpo de la solicitud, Tipo de cuerpo (body) enviado define cómo viaja: Ninguno, x-www-form-urlencoded, form-data, Raw content type (por ejemplo application/json) o application/x-protobuf. Un cuerpo crudo (raw) reemplaza a los parámetros, que quedan deshabilitados; si los necesita, van en el query string de la URL.

Panel Configurar el cuerpo de la solicitud con el selector Tipo de cuerpo enviado y el Content-Type

Autorización

En la pestaña Autorización seleccione el esquema que requiere el servicio:

Autorización Basic Autorización Bearer Token Content-Type de la solicitud del token Parámetros de la solicitud del token Prefijo Bearer y valor del token
  • Basic Authorization: usuario y contraseña, que la plataforma codifica en base64 y envía como Authorization: Basic ....
  • Bearer Token: un token de acceso sin vencimiento, enviado como Authorization: Bearer ....
  • Security Token Service (STS): servicios que exigen obtener un token en una solicitud previa, como OAuth 2.0 u otra autenticación en dos pasos.
Pestaña Autorización con las opciones Basic Authorization, Bearer Token y Security Token Service

Con STS, haga clic en Configurar. Configure la solicitud que obtiene el token e ingrese la ruta al token en su respuesta como JsonPath. Al guardar vuelve a la solicitud principal; el token se envía en la cabecera Authorization con el prefijo Bearer, que puede cambiar.

Configuración del Security Token Service con la solicitud del token y la ruta JsonPath al token

La respuesta

Con una respuesta correcta, pase a Procesar respuesta para obtener los datos en forma de tabla.

Ruta a los datos y Evaluar

Indique con un JsonPath qué elemento de la respuesta se tabula; $ es el objeto raíz. Para esta respuesta, la ruta a los datos es $.data:

Botón para previsualizar la respuesta Previsualización tabulada de la respuesta
{
  "count": 2,
  "data": [
    { "id": 1, "nombre": "Ana", "area": { "nombre": "Ventas" } }
  ]
}
Ruta a los datos con el JsonPath sobre la respuesta del servicio y la previsualización

Previsualice la respuesta. Si alguna celda muestra un objeto JSON, porque hay datos anidados, use Evaluar ruta a los datos: ingrese los nodos a extraer separados por | y, para los hijos de un nodo, un punto, por ejemplo id|nombre|area.nombre. La previsualización muestra una columna por nodo.

Evaluar ruta a los datos con los atributos de cada objeto separados por barra vertical

Cabeceras

Defina de dónde salen los títulos de las columnas. Cuando cada registro es un objeto con atributos, como en el ejemplo, seleccione Sí, son los atributos. Si los títulos vienen en otra parte de la respuesta, ingrese la ruta a las cabeceras como JsonPath.

Identificación de cabeceras con la opción Sí, son los atributos

Validar

La pestaña Validar respuesta muestra la tabla tal como la verá la vista de datos y permite una validación opcional sobre un atributo de la respuesta, para detectar que el servicio informe un error aunque responda con código 200.

Pestaña Validar respuesta con la condición sobre un atributo de la respuesta

Campos extendidos

Los Campos extendidos extraen datos que están fuera de la tabla. Para cada campo ingrese nombre, descripción y ruta. En el ejemplo, el campo total con la ruta $.count recupera la cantidad de registros que informa el servicio.

Campos extendidos con nombre, descripción y ruta JsonPath

Servicios que responden CSV

Para un servicio que devuelve texto separado por comas, use la pestaña REST/CSV; la solicitud se configura igual. Al probar, Procesar respuesta pide el Separador de columnas (coma, punto y coma o barra vertical) y la Codificación del contenido, UTF-8 o Detectar automáticamente; si el servidor la informa en Content-Type, se usa esa.

Guardar y frecuencia

Continuar y completar los metadatos

Haga clic en Continuar. Ingrese el título y la descripción que le permitirán encontrar el origen más adelante. El origen de datos se crea en estado Borrador.

Frecuencia de actualización

Seleccione con qué frecuencia cambian los datos en el servicio: es el primer nivel de caché de la plataforma. Si se actualizan cada hora, seleccione Cada hora; si son datos diarios, Diaria. Con Otro puede ingresar un cron específico. Si tiene dudas, deje Bajo demanda. Luego haga clic en Guardar.

Selector de frecuencia de actualización del origen de datos

Resultado esperado

El servicio REST queda como origen de datos en estado Borrador. Los mapeos, los parámetros y las cabeceras editables se heredan en las vistas de datos y en los métodos de la API; la ruta a los datos y las cabeceras definen la tabla. El siguiente paso es crear una vista de datos sobre este origen.

Errores frecuentes

  • Probar devuelve 401 o 403: el esquema de autorización no coincide con el del servicio. Revise el tipo, las credenciales y el prefijo del token.
  • Probar devuelve 400 o 415 con POST: el Content-Type no es el que espera el servicio, o el cuerpo no es un JSON válido.
  • La previsualización está vacía: la ruta a los datos no apunta a la lista de registros. Verifique el JsonPath contra el cuerpo recibido en Probar.
  • Los títulos de las columnas son números: no se indicó de dónde salen las cabeceras. Seleccione Sí, son los atributos o ingrese la ruta a las cabeceras.

Artículos relacionados