Introducción

Además de poder subir, editar y compartir ficheros a través del Control Panel de Plataforma existe una API REST disponible para realizar estas funciones.

Primero veremos como utilizar esta API de forma directa, utilizando un cliente REST, como puede ser Postman, y después veremos como hacer uso de este API REST a través del cliente java disponible.

Diferentes repositorios de ficheros para diferentes necesidades

Onesait Platform permite almacenar los ficheros en diferentes repositorios, incluso para una misma instalación se pueden tener configurados diferentes tipos simultaneamente. Estos repositorios son:

• MongoDB GridFS: Al ser la base de datos de tiempo real de referencia de la plataforma, se trata de la opción por defecto. Proporciona una gestión básica de ficheros, utilizando las capacidades GridFS de MongoDB.

• MinIO S3: Es el repositorio de ficheros avanzado de Onesait Platform. Proporciona un almacenamiento compatible con S3, junto con herramientas de gestión avanzada de ficheros en Onesait Plaform (previsualización, versionado, almacenamiento estructurado como un Filesystem tradicional…)

• Google Cloud Storage: Implementado en proyectos donde disponer de almacenamiento S3 como servicio es la mejor opción, liberando a los administradores de todas las tareas que implica mantener un gestor de Buckets S3.

Autenticación

EL API del repositorio de ficheros binarios está protegida como el resto de APIs, pudiendose autenticar mediate API Key o mediante OAuth2 consiguiendo un toker Bearer del Identity Manager de Plataforma.

Para obtener el API Key de nuestro usuario, lo más sencillo es consultar desde el controlpanel la opción de APIs propias de la plataforma:

Open

Donde en el modal previo, podemos consultar tanto el token Bearer actual del Identity Manager (al estar logados) o cualquiera de nuestras API Keys (X-OP-APIKey)

Open

Operaciones

Como el resto de APIs de Onesait Platform, se expone desde el controlpanel y su documentación Swagger está disponible bajo la url https://<url>/controlpanel/swagger-ui/index.html?urls.primaryName=Binary#/ (pej: https://lab.onesaitplatform.com/controlpanel/swagger-ui/index.html?urls.primaryName=Binary)

Al haber tres tipos diferentes de repositorios, todas las operaciones que lo necesitan disponen queryParam “repository” donde indicarlo:

Así como todas las operaciones de consulta disponen de un atributo que indica el repositorio donde está almacenado cada fichero

Subir un fichero (POST)

Para subir un fichero, debes hacer una petición POST al endpoint '/controlpanel/binary-repository', con dos parámetros en el body:

• Fichero binario ("file", obligatorio). Tamaño máximo 50 MB.

• Metadatos ("metadata", opcional). Este parámetro se debe enviar en formato text. 

• Repositorio ("repository", opcional, por defecto Mongo Grid FS). En este parámetro se indica dónde quieres guardar el fichero binario. Existen dos opciones "MONGO_GRIDFS", "FILE" (MinIO s3), GCP. Por defecto se almacena en Mongo.

Además de la cabecera de autenticación.

De vuelta recibirás un identificador que servirá para editar y descargar el fichero en el futuro.

Descargarse un fichero (GET)

Para descargar un binario, debes tener el identificador de dicho fichero devuelto en la creación. En caso de no disponer de él, puedes utilizar la operación GET al endpoint ‘/contropanel/binary-repository’ que devuelve el listado total de ficheros

Esta operación devuelve todo el listado de ficheros con el id y el repositorio donde está almacenado cada uno:

Una vez que conocemos su id y su repositorio, podemos hacer una petición GET al endpoint '/controlpanel/binary-repository/{id}', sustituyendo id por el identificador del fichero, que es devuelto por la plataforma en cada inserción.

En el caso de que el fichero binario no sea público, debes insertar la cabecera de autenticación igual que en el resto de operaciones.

Esta operación devuelve el fichero dentro del JSON en base64, por lo que si forzasemos una cabecera Content-Disposition a valor attachment, se descargaría el fichero:

No obstante, tambien se dispone en el API de la operacion GET ‘/controlpanel/binary-repository/download/{id}’ que permite descargar el fichero

Modificar un fichero (POST)

Si tienes permisos para modificar un fichero, puedes hacerlo en el endpoint '/controlpanel/binary-repository/{id}' con método POST, sustituyendo el id por el identificador del fichero binario.

El fichero se actualizará si recibes un HTTP 202.

Eliminar un fichero (DELETE)

Por último, para eliminar un fichero sobre el que tengas permisos, debes hacer una petición DELETE al endpoint '/controlpanel/binary-repository/{id}', sustituyendo el id por el identificador del fichero binario.

Recibirás un HTTP 202 si todo ha ido bien y el fichero ha sido eliminado de la plataforma.

Utilizando el API Java

Si tu objetivo es trabajar con binarios desde Java, existe una API que puedes utilizar.

Esta API contiene las operaciones anteriormente descritas en este artículo.

Para utilizarla, debes importar las dos clases del paquete:

- import com.minsait.onesait.platform.binaryrepository.*;

Este paquete contiene:

• Cliente: BinaryRepositoryClient.java , se encarga de implementar el CRUD del repositorio de binarios, vía REST.

• Modelo: BinaryDataFile.java , este modelo se utilizará para encapsular el fichero binario que se solicite a la plataforma

Inicialización del cliente

Necesitarás inicializar el cliente, pasándole como argumentos, tu usuario y contraseña, así como el servidor o dominio donde esté desplegada la plataforma:

Con tus credenciales, el cliente conseguirá la autenticación OAuth2.

Subida de fichero

Para subir un fichero, basta con llamar al método addBinaryFile(File file, String metadata, RepositoryType repository) del cliente. El fichero deberá ocupar como máximo 50MB.

Descargar un fichero

Para descargar un fichero, hay que hacer uso del método getBinary(String  id, RepositoryType type), que devolverá un objeto del tipo BinaryDataFile, con el binario encapsulado.

Actualizar un fichero

Para actualizar un fichero, se hace uso del método updateBinaryFile(String id, File newFile, String newMetadata, RepositoryType type). En una instalación por defecto fichero deberá ocupar como máximo 50MB.

Borrar un fichero

Por último, para borrar un fichero, se debe llamar al método removeBinaryFile(String id, RepositoryType type)