/
Tutorial avanzado Uso Portal Open Data de Plataforma

Tutorial avanzado Uso Portal Open Data de Plataforma

Introducción

El módulo Open Data de la plataforma Onesait, basado en la herramienta de código abierto CKAN, tiene como objetivo facilitar la publicación, búsqueda y uso de datos. 

Permite subir y gestionar bloques de datos en forma de recursos, los cuales se almacenan como archivos en diversos formatos (CSV, XML, JSON, entre otros). Estos recursos se agrupan en conjuntos de datos (datasets) y son administrados por diferentes organizaciones.

CONCEPTOS BÁSICOS

Recurso

Es el elemento básico con el que trabajaremos. Se trata de un bloque de datos almacenado en un archivo, que puede ser en formatos como CSV, XML, JSON, o un volcado de base de datos, entre otros. Estos recursos pueden tener metadatos asociados que faciliten su visualización y búsqueda.

Dataset

Es la unidad principal utilizada para clasificar y agrupar nuestros recursos. Cada dataset actúa como un contenedor que organiza múltiples recursos relacionados entre sí. Estos permiten a los usuarios encontrar, acceder y utilizar los datos de manera eficiente.

Organización

Elemento raíz que contiene las colecciones de datasets, permitiendo su creación y administración. Además, en la organización se gestionan los usuarios y se definen los permisos que tienen con respecto a los datasets creados.

Grupo

Elemento de clasificación transversal que permite añadir un dataset a un tema específico, como un proyecto, equipo o tópico, dentro de una o varias organizaciones. La visibilidad del dataset dentro del grupo dependerá de si es público o privado.

 Relación entre Organizaciones - Grupos - Datasets 

Roles y Permisos

Existen tres tipos de roles particulares que puede tener un usuario en la herramienta, los cuales son independientes de los roles creados en la plataforma Onesait. Cada rol permite realizar ciertas operaciones, como se explica a continuación:

  • Miembro: Puede ver los datasets privados en una organización.

  • Editor: Puede ver los datasets privados, además de añadir, editar y cambiar la visibilidad de los datasets (hacerlos públicos o privados).

  • Administrador: Tiene los mismos permisos que el editor, pero además puede crear organizaciones y gestionar roles y usuarios.

Funcionalidades disponibles

La plataforma Onesait Platform integra el portal Open Data CKAN de modo que todas las funcionalidades - catalogación de datasets, búsquedas, API de datos abiertos, gestión de metadatos y control de permisos— se exponen directamente a los usuarios a través de la misma interfaz unificada de la plataforma. Esto significa que las tareas habituales (publicar, buscar y descargar datos, o consumirlos vía API) pueden realizarse sin abandonar la plataforma, beneficiándose además de los servicios añadidos que esta aporta —autenticación única, paneles de visualización,...

A continuación se detallan algunas de las operativas más comunes.

Creación de una organización

Para crear una organización, dirígete al apartado de Open Data en el menú y selecciona "Organizations".

En esta sección, verás las organizaciones de las que eres miembro. Para crear una nueva organización, debes tener el rol de administrador en la plataforma. Haz clic en el icono "+" ubicado en la parte superior derecha, como se muestra a continuación.

 En la ventana que se abrirá, se solicitarán los datos necesarios, como el nombre y la descripción de la organización. También podrás subir una imagen como logo. Una vez que hayas completado todos los campos requeridos, haz clic en el botón "Create".

 

Una vez creada la organización, puedes volver al apartado de organizaciones y hacer clic en el icono view para ver los detalles de la organización.

Creación de Grupos

Un grupo es una forma de clasificación transversal que permite agrupar conjuntos de datasets por un tópico específico entre organizaciones. Para crear un grupo, debemos acceder al portal de Open Data. 

Dentro del portal, iremos a la pestaña "Group" (Categorías en español), donde se mostrará la lista de grupos que hemos creado. A continuación, haremos clic en la opción "Add Group" ubicada en la parte superior derecha: 

En el formulario que se abrirá, debemos completar los siguientes campos:

  • Name: Nombre del grupo o categoría.

  • URL: URL para acceder al grupo, que podemos personalizar. Debe ser única y no confundirse con el ID del grupo.

  • Description: Descripción del grupo.

  • Image: Podemos subir una imagen como logo para el grupo.

Una vez que hayamos completado los campos, haremos clic en "Create Group" y seremos redirigidos al detalle de nuestro nuevo grupo.

Para añadir un dataset a un grupo, debemos ir al detalle del dataset y seleccionar la pestaña de grupos. 

Allí, elegiremos el grupo y haremos clic en "Add to group", mostrando así en qué grupos está incluido el dataset.

Definir permisos de acceso y escritura-lectura a usuarios

Como se ha comentado, existen tres tipos de roles que puede tener un usuario en la herramienta, los cuales son independientes de los roles creados en la plataforma Onesait: Miembro, Editor y Administrador.

Para gestionar los usuarios en una organización, accedemos al detalle de la organización y hacemos clic en la opción "Edit". En esta vista, vamos al apartado "Authorizations" ubicado a la izquierda.

En esta sección, seleccionamos el usuario y el rol que queremos asignar a la organización, y hacemos clic en la opción "Insert Authorization". Si todo se realiza correctamente, el usuario se añadirá a la lista de la derecha.

Creación de datasets

Para crear un dataset y subir datos, debemos dirigirnos al menú lateral, acceder al módulo Open Data y seleccionar la opción "Datasets".

 A continuación, aparecerá el listado de datasets actuales a los que el usuario puede acceder o manipular.

 Para crear un nuevo dataset, haremos clic en el botón "+" ubicado en la parte superior derecha. Esto abrirá un formulario que debemos completar para crear el nuevo dataset.

 Una vez que hayamos rellenado el formulario y hecho clic en la opción "Create", aparecerá un pop-up con las opciones para crear nuestro primer recurso dentro del dataset.

Creación de Recursos

Una vez creado el dataset, podemos subir nuestros datos de varias formas. Para ello, iremos a nuestro menú y seleccionaremos la opción "Resources". 

En esta sección, se listarán todos los recursos a los que tenemos acceso o que podemos manipular.

Al igual que en apartados anteriores, haremos clic en la opción "+" para crear un nuevo recurso. Las opciones disponibles son las siguientes: 

 

  • Crear desde una Entidad: Una entidad es un elemento que almacena información similar a una base de datos. Podemos crear un recurso a partir de esta entidad y mostrarlo en el dataset deseado.

  • Crear desde un Fichero: Podemos subir un fichero en formato CSV, XML o JSON. Los datos del fichero se volcarán en una entidad nueva o existente y se publicarán en el dataset destino.

  • Crear desde una URL Externa: Si disponemos de un recurso o fichero online en formato CSV, XML o JSON, podemos procesarlo a través de una URL, realizando su volcado y publicación en el dataset, de manera similar al caso del fichero.

  • Crear desde un Recurso de Plataforma: Podemos elegir un dashboard o una API publicada en la plataforma y publicar su información en el dataset destino. 

Creación de Recursos

Creación de un recurso a partir de un fichero estático    

Para subir un fichero estático, crearemos un recurso utilizando la opción "Creation from file". Aparecerá un formulario con los siguientes campos:

  • Nombre: Rellenar el nombre del recurso.

  • Dataset Destino: Seleccionar el dataset donde se almacenará el fichero.

  • Formato del Fichero: Indicar el formato del fichero (CSV, XML, JSON, etc.).

  • Entidad: Definir si se creará una nueva entidad (marcando la casilla "New Entity") o si se utilizará una entidad existente.

  • Seleccionar Fichero: Elegir el fichero que se subirá haciendo clic en "Select File to upload".

Una vez subido el fichero, se mostrará un esquema de la estructura de datos que se utilizará para su visualización.

El fichero quedará disponible en el portal asociado al Dataset indicado.

Creación de un recurso a partir de un fichero dinámico (actualizando sus datos)

Para subir un fichero dinámico, la opción más conveniente es subir los datos a una entidad y luego actualizar el recurso. Seguimos los mismos pasos que para el fichero estático. Una vez subido el primer fichero, tendremos una entidad con los datos iniciales. Para añadir más datos de un segundo fichero, vamos a "Main Concepts > My Entities".

Hacemos clic en el botón "+" en la parte superior derecha, como si fuéramos a crear una nueva entidad, y seleccionamos la opción "Creation from File".

En el formulario, elegimos el fichero que deseamos subir, desmarcamos la casilla "New Entity" y seleccionamos la entidad a la que queremos añadir los datos.

Después de hacer esto, hacemos clic en "Create" y debería aparecer un mensaje indicando que los registros se han añadido.

Finalmente, actualizamos nuestro recurso. Para ello, lo editamos y hacemos clic en "Update data" en la parte inferior derecha, refrescando así los datos.

Esta operativa se puede realizar además mediante los APIs expuestos en plataforma para facilitar la integración con otros sistemas.

Creación de un recurso a partir de una Tabla existente en una BBDD externa

Para crear un recurso a partir de una tabla de una BBDD externa, primero creamos una conexión a la base de datos. Vamos a la opción "JDBC Database Connections".

En esta sección, se listarán las conexiones existentes. Para crear una nueva, hacemos clic en el botón "+".

Aparecerá un formulario donde rellenaremos los datos de la conexión. Al final, podemos probar la conexión y verificar que todo está correcto.

Una vez creada la conexión, podemos crear una entidad enlazada a la tabla de BBDD. Vamos a "My Entities" y seleccionamos la opción "Creation from Relational Database".

 

En el formulario que aparece, elegimos la conexión creada previamente, la base de datos disponible y la tabla que queremos exportar

Al hacer clic en "Create", aparecerá otra vista donde podemos definir una clave si lo deseamos, y se mostrará la estructura de los datos a exportar. Si todo está correcto, hacemos clic nuevamente en "Create". Si todo ha ido bien, se nos preguntará qué queremos hacer con la nueva entidad. En el pop-up, hacemos clic en "close".

 Al igual que con el fichero, creamos un recurso a partir de la entidad, seleccionando la entidad recién creada y el dataset destino. Dado que se trata de una base de datos externa, en la siguiente ventana disponemos de una herramienta que nos permite consultar y generar consultas SQL. Esto nos permite filtrar y exportar los datos deseados de manera eficiente.

Hacemos clic en "Create" y ya tendremos publicado el recurso desde una base de datos externa. 

Creación de un recurso a partir de una Tabla existente en una BBDD externa vía API (permite acceso al contenido actualizado)

Partiendo de la entidad que hemos creado del punto anterior, podemos consultar el contenido actualizado de una tabla de una BBDD externa mediante una API de plataforma, para crearla nos vamos al apartado de Logic > My Apis

En la vista, se nos muestra las apis que podemos acceder, para crear una nueva, hacemos click al botón “+” en la parte superior derecha

 Nos aparecerá un formulario en el que se nos pide en la parte izquierda del formulario, la información básica, que tipo y entidad vamos a obtener los datos, en la parte derecha los servicios o métodos de nuestra api, podemos ir seleccionándolas.

Podemos crear una consulta personalizada a través del botón “+Query Custom”, nos aparecerá un popup en el que se nos pide la consulta y el tipo de servicio que deseamos crear

Una vez tengamos todo listo, hacemos click en el botón “Create” y tendremos nuestra api con el estado “draft”, para publicarla, debemos dirigirnos a “My Apis” y la publicamos como se muestra a continuación

 

Ahora creamos un recurso nuevo, esta vez elegiremos la opción “Creation from Platform resource”

Aparecerá un  formulario en el que rellenaremos la información necesaria y seleccionaremos la API creada:

Una vez creada, podemos visualizar el Api dentro del recurso en el portal del Open Data:

Creación de un recurso por URL

Para subir un recurso en forma de URL externa, seleccionaremos la opción "Creation from external URL". Al igual que en el caso de un fichero, se abrirá una vista en la que deberemos completar los siguientes campos:

  • Nombre: Rellenar el nombre del recurso.

  • Entidad: Definir si se creará una nueva entidad (marcando la casilla "New Entity") o si se utilizará una entidad existente.

  • Dataset Destino: Seleccionar el dataset donde se almacenará el recurso.

  • Formato del Fichero: Indicar el formato del fichero remoto en la URL (CSV, XML, JSON, etc.).

  • Link: Proporcionar el enlace del recurso externo, asegurándose de que sea accesible y público.     

Creación de recurso con modo de visualización de Mapa

Para crear una visualización de mapa en un recurso, en la vista que disponemos de los datos, tenemos una opción "Map"

En él podemos seleccionar que datos representan la latitud y longitud, y hacer click en el botón update, se nos representará los puntos en el mapa

Creación de recurso a partir de Dashboard de Plataforma

En plataforma, podemos exportar un dashboard a un dataset para su visualización, para ello primero crearemos un dashboard, nos vamos al apartado de Visualization > My Dashboards, a continuación, haremos click en el botón “+”

En el formulario a continuación rellenaremos los campos obligatorios y hacemos click en la opción “Create” en la esquina superior derecha

Ahora, se nos abrirá una ventana en blanco como a continuación

En el haremos click en el botón “+” y nos aparecerá las opciones para añadir, en este caso añadiremos un mapa

Se nos abrirá un popup donde indicaremos de que entidad obtendremos los datos, una vez realizado, hacemos click en el botón continuar

Ahora aparecerá otro popup en el que indicaremos que campos representan las coordenadas, una vez seleccionados, hacemos click en “Create”

Ya tendríamos nuestro dashboard en forma de mapa, guardamos los cambios con el icono de guardar.

Ahora para exportarlo al open data, debemos crear un recurso nuevo como hemos vistos en otros apartados, ahora seleccionando la opción “Creation from Platform resource”   

En el nos aparecerá el siguiente formulario en el que debemos seleccionar nuestro dashboard creado, continuamos con el botón “Create”

Ya creado, para su visualización nos dirigimos al portal de CKAN y consultando el recurso, podemos ver nuestro dashboard creado.

Uso de APIS Portal Open Data

El Open Data dispone de un API que permite crear datasets y recursos, siendo el endpoint para el entorno de lab el siguiente https://lab.onesaitplatform.com/controlpanel/swagger-ui/index.html?urls.primaryName=Open%20Data%20Portal#/

Creación de un dataset

A través de una petición POST, informando los campos que aparecen en el JSON de ejemplo podemos crear un dataset

Creación de un recurso

A través de una petición POST, informando los campos que aparecen en el JSON de ejemplo podemos crear un recurso, de esta forma se crea tanto el recurso como las vistas de los datos de dicho recurso

Actualización de recursos

Se puede actualizar el recurso con los datos de la entidad creada en la plataforma Onesait, realizando una petición GET con el id del recurso

Por otra parte, el CKAN dispone de un api propio por el cual se pueden dar de alta y modificar datasets y recursos a conveniencia, estos pueden requerir mas peticiones para lograr los mismos resultados  que con el api del Open Data, comentar que el endpoint para acceder al CKAN del Open Data es “https://lab.onesaitplatform.com/opendata/api/3/action”, a continuación abarcaremos algunos métodos interesantes del API:

Creación de un dataset (package_create)

Para crear un dataset, a través de una petición POST al método “package_create” incluiremos en el cuerpo un JSON con los siguientes campos:

  • Name: Nombre del nuevo dataset, que servirá como identificador para añadir posteriormente recursos.

  • Title: Nombre o título que se mostrará en la web

  • Owner_org: Nombre de la organización a la que pertenecerá el dataset

  • Tags: Etiquetas para facilitar su búsqueda

Petición de ejemplo:

Creación de un recurso (resource_create)

Una vez creado el dataset, para subir un recurso debemos realizar una petición POST al método “resource_create” incluyendo los siguientes parámetros en el cuerpo en formato form-data

  • Package_id: Nombre del dataset al que vamos añadir el recurso

  • Name: Nombre que se mostrará del recurso

  • Format: Formato del recurso (por ejemplo, CSV, XML, JSON)

  • Resource_Type: Tipo de recurso

  • Upload: Si se desea subir un archivo, indicar la ubicación del mismo en el sistema de archivos.

  • URL:  Si se desea subir un recurso remoto o un enlace, añadir la URL de dicho recurso. 

Petición de ejemplo:

Modificación de un recurso (resource_update)

Podemos modificar un recurso a través de una petición POST al método “resource_update”, incluyendo los siguientes parámetros en el cuerpo en formato form-data

  • id: Id del recurso a editar

  • Name: Nombre que se mostrará del recurso

  • Format: Formato del recurso (por ejemplo, CSV, XML, JSON)

  • Resource_Type: Tipo de recurso

  • Upload: Si se desea subir un archivo, indicar la ubicación del mismo en el sistema de archivos.

  • URL:  Si se desea subir un recurso remoto o un enlace, añadir la URL de dicho recurso. 

 Petición de ejemplo:      

Crear metadata de un recurso (datastore_create)

Para añadir metadatos a un recurso y facilitar una vista rápida, realizaremos una petición POST al método “datastore_create”. En el cuerpo de la petición, incluiremos la estructura de datos y los registros en formato JSON con la siguiente estructura:

  • Resource_id: Id del recurso

  • Force: Bandera que permite escribir en recursos de solo lectura

  • Fields: Lista de campos que definirán la estructura de datos

  • Records: Lista de registros a añadir que cumplen la estructura del campo Fields

 Petición de ejemplo:

Añadir metadata de un recurso (datastore_upsert)

Se puede añadir un registro en los metadatos de un recurso con una petición POST al método “datastore_upsert”. En el cuerpo de la petición en formato JSON, solo debemos indicar el identificador y el flag de “forcé” si es necesario para recursos de solo lectura:

  • Resource_id: Id del recurso

  • Method: Se indica como se desea insertar los nuevos registros, disponemos de los siguientes

    • upsert: Actualiza los registros si ya existen, o los inserta si no existen. Este es el método por defecto

    • insert: Inserta nuevos registros. Si los registros ya existen, se producirá un error

    • update: Actualiza los registros existentes. Si los registros no existen, se producirá un error

  • Records: Lista de registros que insertaremos o modificaremos

Petición de ejemplo:            

 Borrar metadata de un recurso (datastore_delete)

Podemos eliminar los metadatos de un recurso para volverlos a crear, realizaremos una petición POST al método “datastore_delete”. En el cuerpo de la petición en formato JSON, solo debemos indicar el identificador y el flag de “forcé” si es necesario para recursos de solo lectura:

  • Resource_id: Id del recurso

  • Force: Bandera que permite escribir en recursos de solo lectura

 Petición de ejemplo:

Crear vista de un recurso (resource_view_create)

Por último, para visualizar los metadatos de un recurso, debemos crearlo a través de una petición POST al método “resource_view_create”. En el cuerpo de la petición a través de un formulario, indicaremos el identificador, el titulo a mostrar, y el tipo de vista:

  • Resource_id: Id del recurso

  • Title: Nombre o título que se mostrará en la web

  • View_type: Tipo de vista en las que tenemos las siguientes:

    • Grid View (recline_view): Muestra los datos en una tabla interactiva.

    • Graph View (recline_graph_view): Permite visualizar los datos en forma de gráficos (barras, líneas, etc.).

    • Map View (recline_map_view): Utiliza datos geoespaciales para mostrar mapas interactivos.

    • Text View (text_view): Muestra el contenido de archivos de texto.

    • Image View (image_view): Visualiza imágenes directamente en la página del recurso.

    • PDF View (pdf_view): Permite visualizar archivos PDF.

    • Web Page View (webpage_view): Muestra el contenido de una URL como una vista incrustada

 Petición de ejemplo: