Ingesta desde S3 Bucket
Descripción general
La ingesta de archivos desde un bucket S3 es una forma más de ingerir archivos desde una fuente diferente (AWS S3).
Desde la perspectiva del procesamiento del contenido del archivo, esto será lo mismo que para la ingesta basada en archivos locales, pero la fuente del archivo es diferente.
El procesamiento del archivo se activa a través de una notificación de Kafka y los siguientes dos puntos de integración son clave para el procesamiento:
-
File available: cuando el archivo está disponible para su procesamiento, el sistema bancario que carga el archivo DEBE enviar una notificación Kafka a reachability. Esto es procesado por el conector de ingesta de archivos, notificando que hay un archivo disponible para procesar en un bucket S3.
-
File processed: cuando el archivo ha terminado de procesarse, se envía un mensaje File Processed Notification al tema File Processed (si sendAcknowledgement solicitado), notificando al sistema bancario que el archivo ha finalizado el procesamiento (con una indicación clara del estado).
Se admiten los siguientes tipos de archivos: XML, TXT, JSON.
Formato de notificación y mapeo de errores a OutcomeDescription
Actualmente, hay 2 tipos de notificaciones:
-
File Available Notification message: Notifica al ingestor de archivos de reachability que un archivo está disponible para procesar
-
File Processed Notification message: Notifica al sistema bancario que el procesamiento del archivo ha finalizado (con una indicación clara del estado)
El formato de las notificaciones es el siguiente:
Formato de notificación para el mensaje de File Available Notification
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"requestId": {
"type": "string",
"description": "Un identificador único de la solicitud de notificación"
},
"fileProvider": {
"type": "string",
"description": "Indica qué File Operations Adapter usar, p. ej., S3, EFC"
},
"filePath": {
"type": "string",
"description": "La ruta absoluta del archivo; para S3 debe ser una URL de S3, ver https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html#API_GetObject_RequestSyntax"
},
"fileName": {
"type": "string",
"description": "El nombre del archivo; siempre debe comenzar con el tipo de archivo, p. ej., BANKDIRECTORYPLUS_V3_FULL_foo_bar.xml"
},
"uploadedAt": {
"type": "string",
"format": "date-time",
"description": "Marca de tiempo que indica cuándo se subió el archivo"
},
"sendAcknowledgment": {
"type": "boolean",
"description": "Si es necesario enviar una confirmación del procesamiento del archivo"
}
},
"required": [
"requestId",
"fileProvider",
"filePath",
"fileName",
"uploadedAt",
"sendAcknowledgment"
]
}Formato de notificación para el mensaje de File Processed Notification
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"requestId": {
"type": "string",
"description": "Un identificador único de la solicitud de notificación que se está confirmando"
},
"fileProvider": {
"type": "string",
"description": "Copiado de la entrada"
},
"filePath": {
"type": "string",
"description": "Copiado de la entrada"
},
"fileName": {
"type": "string",
"description": "Copiado de la entrada"
},
"processingFinishedAt": {
"type": "string",
"format": "date-time",
"description": "Marca de tiempo que indica cuándo terminó el procesamiento del archivo"
},
"outcomeCode": {
"type": "string",
"description": "Un código que describe el resultado, lista por definir"
},
"outcomeDescription": {
"type": "string",
"description": "Una descripción textual del código"
}
},
"required": [
"requestId",
"fileProvider",
"filePath",
"fileName",
"processingFinishedAt",
"outcomeCode",
"outcomeDescription"
]
}Cuando outcomeCode es SUCCESS, la descripción del resultado es Success; y cuando outcomeCode es FAILED, entonces outcomeDescription es el mensaje de excepción que explica el error ocurrido.
Acuse de recibo
Cuando se recibe el mensaje File Available Notification, dentro del mensaje hay un booleano sendAcknowledgement. El mensaje File Processed Notification se enviará o no según ese valor una vez que termine el procesamiento del archivo.
Configuraciones de credenciales del cliente S3
Descripción de credenciales
Al interactuar con AWS, se deben especificar credenciales de seguridad de AWS para verificar la identidad y los permisos para acceder a los recursos solicitados. AWS utiliza estas credenciales de seguridad para autenticar y autorizar las solicitudes.
Por ejemplo, para descargar un archivo protegido de un bucket de Amazon Simple Storage Service (Amazon S3), las credenciales deben permitir ese acceso. Si las credenciales no autorizan la descarga, AWS deniega la solicitud.
Hay diferentes tipos de usuarios en AWS, y todos los usuarios de AWS tienen credenciales de seguridad. Estos usuarios incluyen al propietario de la cuenta (usuario raíz), usuarios en AWS IAM Identity Center, usuarios federados y usuarios de IAM.
Los usuarios tienen credenciales de seguridad de largo o corto plazo. Los usuarios raíz, los usuarios de IAM y las access keys tienen credenciales a largo plazo que no caducan. Para proteger las credenciales a largo plazo, deben existir procesos para gestionar access keys, cambiar contraseñas y habilitar MFA.
Las access keys de AWS se proporcionan para realizar llamadas programáticas a AWS o usar la AWS Command Line Interface o AWS Tools for PowerShell. Se recomienda usar access keys de corto plazo cuando sea posible.
El cliente S3 actualmente admite Static Credentials para la gestión de acceso: (con más opciones en futuras versiones)
Static Credentials (Modo predeterminado)
Cuando se crea una access key de largo plazo, se crean un access key ID (por ejemplo, AKIAIOSFODNN7EXAMPLE) y una secret access key (por ejemplo, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY) como un conjunto. La secret access key solo está disponible para descargar en el momento de la creación. Si no se descarga o se pierde, se debe crear una nueva.
Configuración:
# Explicit configuration (optional, default is "static")
ipf.file-manager.s3.credentials-provider = static
# Required credentials
ipf.file-manager.s3.credentials.access-key-id = <your-access-key>
ipf.file-manager.s3.credentials.secret-access-key = <your-secret-key>Características: * Usa credenciales de acceso de largo plazo * Las credenciales se almacenan en la configuración * Fácil de configurar pero menos seguro para entornos de producción * Adecuado para desarrollo y pruebas
Uso de archivos versionados
Si el mismo archivo existe con diferentes versiones, por defecto se recoge el archivo con la versión más reciente. Para recoger una versión específica, se debe incluir el parámetro de consulta versionId en la solicitud.
Ejemplo del mensaje de entrada con una versión específica del archivo:
| Key | Value |
|---|---|
requestId |
bicdir2018-req001 |
fileProvider |
s3 |
filePath |
s3://test-bucket.s3.amazonaws.com/BICDIR2018_V1_FULL.txt?versionId=HKPnHafHX2ufQ-_faJX-dw |
fileName |
BICDIR2018_V1_FULL.txt |
sendAcknowledgment |
true |
Configuración adicional
Para instrucciones detalladas de configuración y guías de instalación, consulta Configuración de ingesta de archivos desde bucket S3.