# File System Operations (FSO) API Implementa los servicios de un Resources Directory (según el RAAM de Induxsoft) a través de una API pública (web services) y privada (biblioteca de funciones). ## Enrutamiento público La extensión .fso está dirigida hacia los programas de la API FSO que exponen servicios, revise el ```ext.map``` de la BWL. ## Servicios Web ### Listar carpetas y/o archivos End point: uri/lst.fso Método HTTP: GET Devuelve un objeto JSON con información del contenido de la URI desde la que se invocó o bien, la que se haya especificado en los parámetros de la URL (GET) si están admitidos. #### Parámetros GET admitidos (todos son opcionales): * filter. Una cadena de filtro para los archivos, p.e. *.txt * deep. Numérico que indica la profundidad de búsqueda en sub-carpetas, predeterminado 999 * search. Una cadena que será buscada en el contenido de archivos * mode. Numérico: 0 (predeterminado) - Devuelve archivos y carpetas, 1-Solo carpetas, 2- Solo archivos y 3-Solo resultados de búsqueda en archivos * base_path. Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri * host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base. * uri. Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados De manera predeterminada, los parámetros en la URL base_path y host son excluyentes entre sí y son ignorados a menos que establezca ```@dklfso_multisites=@true``` en fso.config.dkl Si se omite el parámetro uri, se asume que la URI es la que corresponde a la invocación del servicio lst.fso. #### Privilegios requeridos Se requiere que el usuario esté autenticado y cuente con alguno de los siguientes: * dkl_fso_list * read + plus * write * admin Ejemplos: ``` https://misitioweb.tld/lst.fso https://misitioweb.tld/lst.fso?filter=*.txt https://misitioweb.tld/lst.fso?search=guanabanas&filter=*.txt&mode=3 ``` ### Obtener metadatos de una carpeta o archivo Devuelve un objeto JSON con los metadatos de un archivo o carpeta End point: uri/get.fso Método HTTP: GET #### Parámetros GET admitidos (todos son opcionales): * base_path. Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri * host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base. * uri. Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados De manera predeterminada, los parámetros en la URL base_path y host son excluyentes entre sí y son ignorados a menos que establezca ```@dklfso_multisites=@true``` en fso.config.dkl Si se omite el parámetro uri, se asume que la URI es la que corresponde a la invocación del servicio get.fso. #### Privilegios requeridos Se requiere que el usuario esté autenticado y cuente con alguno de los siguientes: * dkl_fso_getprops * read + plus * write * admin Ejemplo: ``` https://misitioweb.tld/documento.docx/get.fso ``` ### Establecer metadatos de una o varias carpetas o archivos End point: uri/set.fso Método HTTP: POST o PUT Se admiten los siguientes parámetros en la URL de solicitud (todos son opcionales): * base_path. Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri * host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base. * uri. Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados De manera predeterminada, los parámetros en la URL base_path y host son excluyentes entre sí y son ignorados a menos que establezca ```@dklfso_multisites=@true``` en fso.config.dkl Si se omite el parámetro uri, se asume que la URI es la que corresponde a la invocación del servicio set.fso. Cuerpo de la solicitud (payload): ``` Content-Type: application/json;charset=utf-8 { "uri1":{ "properties":{"clave":"valor",...} "privileges":{ "write":[{"user":"admin",...},...] } }, "uri2":{...}, ... "uriN":{...} } ``` Las claves "uri1",..."uriN" del cuerpo de la solicitud y que indican los recursos a actualizar, son relativas a la uri de la URL a menos que inicien con el caracter ```/```. Para indicar que el recurso a afectar es la URL desde la que se invoca el servicio, use como clave ```.```. Ejemplos: Asumiendo la URL de solicitud como: ```https://misitioweb.tld/carpeta_ejemplo/set.fso``` Las uri de los recursos a afectar indicadas: ``` { ".":{ -- Afecta a la carpeta 'carpeta_ejemplo' -- }, "subcarpeta/archivo.txt":{ -- Afecta al archivo '/carpeta_ejemplo/subcarpeta/archivo.txt' -- } "notas.txt":{ -- Afecta al archivo '/carpeta_ejemplo/notas.txt' -- } "/otra_carpeta/texto.txt":{ -- Afecta al archivo '/otra_carpeta/texto.txt' -- } } ``` Respuesta de ejemplo: ``` Content-Type: application/json;charset=utf-8 { "success":true, "data": { "uri1":{"props_done":true, "privs_done":true }, ... } } ``` #### Privilegios requeridos Se requiere que el usuario esté autenticado y cuente con alguno de los siguientes: * dkl_fso_setprops * write * admin ### Subir uno o varios archivos Este servicio permite subir archivos codificados como ```multipart/form-data``` en la ubicación (URI) de carpeta indicada. Si los archivos ya existen, serán sobre-escritos (si el usuario que invoca el servicio tiene los privilegios suficientes). End point: uri/upl.fso Método HTTP: POST o PUT Content-Type: multipart/form-data Se admiten los siguientes parámetros en la URL de solicitud (todos son opcionales): * base_path. Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri * host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base. * uri. Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados De manera predeterminada, los parámetros en la URL base_path y host son excluyentes entre sí y son ignorados a menos que establezca ```@dklfso_multisites=@true``` en fso.config.dkl Si se omite el parámetro uri, se asume que la URI es la que corresponde a la invocación del servicio upl.fso. Fragmento HTML de ejemplo: ``` html <html> <body> <h1>Ejemplo: Subir archivo</h1> <form action="upl.cmd" enctype="multipart/form-data" method="POST"> <input type="file" id="myFile" name="filename"> <input type="submit"> </form> </body> </html> ``` Ejemplo de respuesta (JSON) tras enviar dos archivos: ``` Content-Type: application/json;charset=utf-8 { "success":true, "data": { "nombre_archivo1":{"done":true}, "nombre_archivo2":{"done":false,"message":"No autorizado"}, ... } } ``` #### Privilegios requeridos Se requiere que el usuario esté autenticado y cuente con alguno de los siguientes: * dkl_fso_upload * write * admin Adicionalmente, para permitir subir archivos de extensiones consideradas de riesgo configuradas en la variable ```@dklfso_danger_files_ext``` de fso.config.dk, se requiere alguno de los siguientes: * dkl_fso_danger * write + plus * admin ### Acciones sobre el sistema de archivos Este servicio permite las siguientes acciones directamente sobre el sistema de archivos: * Crear una carpeta * Eliminar una carpeta y todo su contenido * Copiar un archivo * Mover un archivivo * Renombrar un archivo * Eliminar un archivo End point: uri/do.fso Método HTTP: POST o PUT Se admiten los siguientes parámetros en la URL de solicitud (todos son opcionales): * base_path. Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri * host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base. * uri. Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados De manera predeterminada, los parámetros en la URL base_path y host son excluyentes entre sí y son ignorados a menos que establezca ```@dklfso_multisites=@true``` en fso.config.dkl Si se omite el parámetro uri, se asume que la URI es la que corresponde a la invocación del servicio do.fso. Las claves "uri1",..."uriN" del cuerpo de la solicitud y que indican los recursos a actualizar, son relativas a la uri de la URL a menos que inicien con el caracter ```/```. Para indicar que el recurso a afectar es la URL desde la que se invoca el servicio, use como clave ```.```. Cuerpo de la solicitud (payload): ``` Content-Type: application/json;charset=utf-8 { "uri1":{ "action":"delete" }, "uri2":{ "action":"mkdir" }, "uri3":{ "action":"copy", "to":"uri_destino"}, "uri4":{ "action":"move", "to":"uri_destino"}, "uri5":{ "action":"rename", "as":"nuevo_nombre"} ... "uriN":{...} } ``` Ejemplo de respuesta (JSON): ``` Content-Type: application/json;charset=utf-8 { "success":true, "data": { "uri1":{"done":true}, "uri2":{"done":false,"message":"No autorizado"}, ... } } ``` #### Privilegios requeridos Se requiere que el usuario esté autenticado y cuente con alguno de los siguientes: * dkl_fso_mkdir - Para crear carpetas * dkl_fso_copy - Para copiar archivos * dkl_fso_move - Para mover archivos * dkl_fso_delete - Para eliminar archivos y carpetas * dkl_fso_rename - Para renombrar archivos * dkl_fso_overwrite - Para sobrescribir archivos en el destino al copiar o mover * write (crear carpetas, copiar, mover, eliminar, sobrescribir y renombrar) * write + plus (Igual que write, pero incluyendo extensiones de archivos con extensiones de riesgo) * admin (Igual que write + plus) Adicionalmente, para permitir escribir o renombrar archivos con extensiones consideradas de riesgo configuradas en la variable ```@dklfso_danger_files_ext``` de fso.config.dk, se requiere alguno de los siguientes: * dkl_fso_danger * write + plus * admin ## Funciones disponibles en fso.dk fso.dk requiere que previamente se incluya el archivo de configuraciones fso.config.dk y depende de functions.dkh, serialize.dkh y webauth.dkl Ejemplo: ``` #include "dkli.dkh" #! program "ejemplo" { #include "functions.dkh" #include "serialize.dkh" #include "webauth.dkl" #include "_protected/fso/fso.config.dk" #include "_protected/fso/fso.dk" //..su código } ``` fso.dk contiene las siguientes funciones de interés para el programador del back-end: ### dklfso.isprotected::uri Devuelve ```@true``` si la cadena uri indicada es una subcarpeta o archivo en una subcarpeta del carpeta protegida del sitio Web. ### dklfso.createObjectInfo::base_path,uri Devuelve una referencia a una estructura de datos con toda la información de metadatos de un archivo o carpeta en el sistema local, o bien @null si no se encuentra el recurso. * base_path - Es una cadena que representa la ruta de base del sitio Web en el sistema local * uri - Es una cadena que representa la ruta relativa a base_path del recurso (archivo o carpeta) en el sistema local ### dklfso.list::&params Devuelve un objeto con toda la información de carpetas y archivos, es la misma respuesta que el servicio lst.fso invocado desde el propio backend. ```params``` es una referencia a una estructura que puede tener los siguientes parámetros: * base_path. (Requerido) Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri * uri. (Requerido) Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados * host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base, si se indica este parámetro no se ignorará base_path por lo que este último puede excluirse. * filter. (Opcional) Una cadena de filtro para los archivos, p.e. *.txt * deep. (Opcional) Numérico que indica la profundidad de búsqueda en sub-carpetas, predeterminado 999 * search. (Opcional) Una cadena que será buscada en el contenido de archivos * mode. (Opcional) Numérico: 0 (predeterminado) - Devuelve archivos y carpetas, 1-Solo carpetas, 2- Solo archivos y 3-Solo resultados de búsqueda en archivos ## Metadatos Los metadatos asociados a una carpeta o archivo son propiedades extendidas (clave/valor) o el manifiesto de privilegios. ### Propiedades extendidas Se almacenan en archivos en formato JSON con extensión ```._m_``` a menos que indique lo contrario en fso.config.dk Las propiedades extendidas de una carpeta se encuentran en el archivo ```._m_``` (archivo sin nombre, solo extensión) dentro de la misma. Para las propiedades extendidas de los archivos, se emplean archivos con el mismo nombre y extensión, más la extensión ```._m_```, p.e. para un archivo denominado ```notas.docx```, existirá un archivo de propiedades extendidas llamado ```notas.docx._m_``` Si no existe el archivo ```._m_``` de propiedades extendidas, las únicas propiedades del archivo o carpeta son las que corresponden al sistema de archivos: nombre (incluyendo extensión), fecha y hora de creación, fecha y hora de último acceso y fecha y hora de última escritura (todas las fechas y horas en formato UTC) ### Manifiesto de privilegios Se almacenan en archivos en formato JSON con extensión ```._p_``` a menos que indique lo contrario en fso.config.dk El manifiesto de privilegios de una carpeta se encuentran en el archivo ```._p_``` (archivo sin nombre, solo extensión) dentro de la misma. Para el manifiesto de privilegios de los archivos, se emplean archivos con el mismo nombre y extensión, más la extensión ```._p_```, p.e. para un archivo denominado ```notas.docx```, existirá un archivo de manifiesto de privilegios llamado ```notas.docx._p_``` Si no existe un archivo de manifiesto de privilegios para un archivo o carpeta, aplica la herencia ascendente, es decir, se heredan los privilegios del manifiesto de la carpeta padre y si no existe, entonces la del padre del padre, etc. ### Importante Ni los archivos de propiedades extendidas ni los archivos de manifiesto de privilegios se generan o existen de forma predeterminada, deberá crearlos manualmente o a través del servicio set.fso ## Privilegios de operaciones específicas FSO API asume que existen los privilegios básicos de BWL: read, write, plus y admin Adicionalmente, define privilegios para operaciones específicas y sus equivalencias (mapa de resolución de privilegios) con respecto a los privilegios básicos en fso.config.dk, lea el código fuente para comprender mejor o realizar personalizaciones.