¶ 1. Sobre el envío y recepción de grandes archivos
En el marco del intercambio de información entre órganos de la administración del Estado muchas veces es necesario intercambiar archivos digitales de gran tamaño, los cuales no pueden ser enviados a través de APIs tradicionales.
El Nodo de Interoperabilidad entregado por Gobierno Digital tiene la capacidad de intercambiar archivos de cualquier tamaño gracias a un protocolo especialmente diseñado para ese fin.
A continuación se detalla cómo habilitar y utilizar esta capacidad de intercambio.
¶ 2. Habilitar un servicio para recibir archivos
En el archivo config.json del Nodo se debe agregar un nuevo servicio donde se indique tanto la carpeta local donde se almacenará el archivo a recibir como el servicio que recibirá la metadata.
Esta sección se agrega en: proveedor
Si la sección “seguridad” no existe, la debe crear.
“proveedor”: [
{
"nombre": "NombreDelServicio",
"origen": {
"tipo": "EXCHANGEFILE",
"rutaLocal": "http://servicio_querecibe_metadata",
"carpetaDestino": "/recibidos/"
},
"rutaExterna": "/recepcionArchivos",
"tps": 2,
"fullduplex": true
}
El servicio NombreDelServicio debe ser agregado al catálogo de servicios indicando que es del tipo “EXCHANGEFILE” además de indicar que organismos tendrán acceso a él. Este paso lo realiza la SGD a pedido del organismo dueño del servicio receptor.
¶ 3.- Configurar el nodo del que envía
Cuando ya esté habilitado el servicio del receptor y se hayan otorgado los permisos de acceso para un consumidor, este puede configurar su Nodo para hacer uso del servicio.
En el archivo config.json del Nodo se debe agregar el servicio como consumidor.
Esta sección se agrega en: consumidor
“consumidor”: [
{
"nombre": "NombreDelServicio",
"rutaLocal": "/envio_archivos_a_organismo_x"
}¶ 4. Envíar un archivo
Una vez configurado el Nodo del emisor se debe llamar al servicio por POST indicando la ruta local del archivo a enviar y con la metadata en el body en formato JSON.
POST
http://localhost:8085/envio_archivos_a_organismo_x?rutaArchivoLocal=/ruta/del/archivo/archivo_muy_pesado.zip
Body: { "campo": "valor", “otro_campo”: “otro valor” }
Esto iniciará la transferencia del archivo y de los metadatos al Nodo del receptor, el cual quedará almacenado en la carpeta que se configuró para recibir los archivos.
Cuando el proceso termine el Nodo retornará la respuesta que dió el receptor en el Body.
¶ 5. Dónde encontrar el archivo
El archivo recibido se almacena en una subcarpeta específica de la transferencia dentro de la carpeta indicada en la configuración.
"carpetaDestino": "/recibidos/"
Quedando en este tipo de estructura:
{carpeta_destino}/{subcarpeta_del_mensaje}/
Por lo que en el ejemplo dado quedaría:
/recibidos/FILETRANSFER.7.01JX6KY2VBK79THG2MA2DP35NG/
En esta carpeta se encontrará el archivo transferido (archivo_muy_pesado.zip) así como un archivo de texto llamado “mensaje.txt” que contiene la metadata del envío.
¶ 6. Flujo técnico del protocolo de envío de archivos
El envío de archivos grandes se realiza a través de streaming sobre HTTP/2.
0.- Los sistemas del organismo que desea enviar el archivo llaman al servicio del nodo por POST indicando la ruta del archivo a transferir y un JSON que irá como metadata (el JSON va en el body).
(Es necesario que desde la máquina donde está alojado el Nodo tenga acceso al archivo)
1.- El nodo del emisor solicita un token de acceso al servidor central de PISEE
2.- El Nodo del emisor establece una conexión segura con el Nodo del receptor mediante HTTP/2 utilizando Mutual TLS para autenticarse, el token obtenido en el paso 2 para autorización.
3.- El Nodo del emisor envía la metada del envío, que se compone de datos del envío mismo (fecha, hora, id) y del JSON que recibió en el body.
4.- Cuando el nodo del receptor acepta la comunicación abre un proceso de streaming en el cual el emisor irá mandando el archivo en bloques y el receptor irá escribiendo esos bloques en un archivo en la carpeta de destino.
5.- Se almacena el archivo en el destino además del mensaje de metadata en una subcarpeta específica para el envío.
6.- Al finalizar los paquetes el nodo del receptor llama a la API interna donde el organismo receptor espera el mensaje de que llegó el archivo.
7.- El Nodo del receptor responde que el envío está terminado y adjunta la respuesta de la API del receptor.
8.- El Nodo del emisor entrega la respuesta del emisor al sistema que inició el envío.
Para toda esta comunicación se utilizó el mismo canal de comunicación TCP del Nodo sin requerir ni puertos extras ni otros protocolos adicionales teniendo la garantía de que el canal se abre con el envío y se cierra al terminar este y dicho canal solo se abre ante peticiones correctamente autenticadas y autorizadas.