| Table of Contents |
|---|
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.
Autenticación
Puesto que se necesita autenticación para realizar estas operaciones, a excepción de GET en algunos casos, necesitas autenticarte a través de OAuth. Para ello debes hacer una petición GET a la ruta '/api-ops/login/username/{username}/password/{password}', sustituyendo los parámetros contenidos en llaves ({}).
...
Si las credenciales son correctas, recibirás un token de access, "access_token". Este token es el que utilizarás en todas las peticiones como cabecera de autenticación.
Esta cabecera se indicará tal y como se muestra a continuación:
...
NOTA: Hay que anteponer "Bearer " al token de acceso.
...
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:
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)
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). Máximo 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 queremos quieres guardar el fichero binario. Existen dos opciones "MONGO_GRIDFS", y "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.
...
Si introducimos este enlace en un navegador, en vez del JSON recibirirás el fichero binario.
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 PUTPOST, sustituyendo el id por el identificador del fichero binario.
Al igual que con la subida de ficheros, necesitas indicar:
...
Metadatos ("metadata" , es opcional)
...
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.De la misma forma que en el PUT, recibirás
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 Postartículo.
Para utilizarla, debes importar las dos clases del paquete:
...
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
| Info |
|---|
Nota: Para trabajar con diferentes tipos de repositorios hay que utilizar la verisón 3.3.6-RELEASE del API. <dependency> <groupId>com.minsait.onesait.platform</groupId> <artifactId>onesaitplatform-java-client</artifactId> <version>3.3.6-RELEASE</version> </dependency> |
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 te 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). El 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)
...
