Administrador de Archivos S3

El administrador de archivos S3 es adecuado para la integración con sistemas de almacenamiento remoto que son compatibles con Amazon S3. API.

Maven Dependency

Para utilizar el Administrador de Archivos S3 en su aplicación, incluya la siguiente dependencia:

    <dependency>
        <groupId>com.iconsolutions.ipf.filemanager</groupId>
        <artifactId>ipf-file-manager-s3</artifactId>
    </dependency>

Escriba la respuesta - Versioning

Como se detalla en el API Referencia, el FileWriter escriba métodos que devuelvan un envuelto WriteResponse objeto.

Cuando S3 Versioning está habilitado, el WriteResponse version() el método devolverá el String versionId producido por S3.

Cuando S3 Versioning está deshabilitado, el WriteResponse version() el método devolverá null.

Configuración

Property Grouping: ipf.file-manager.s3

Key Description Default Value

ipf.file-manager.s3.checksum-algorithm

The algorithm used to verify data integrity during transfers. CRC32 provides a good balance between performance and reliability.

 
"CRC32"

ipf.file-manager.s3.chunk-encoding-enabled

Controls whether to use chunked transfer encoding for uploading files. When disabled, the entire file content is buffered before upload.

 
false

ipf.file-manager.s3.credentials-provider

Values:
- static: Uses fixed access/secret keys specified in configuration
- sts-web-identity: Uses AWS IAM OIDC/Web Identity token provider for EKS/Kubernetes environments
- default: Uses AWS Default Credentials Provider Chain (docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html#credentials-default)
Follows this order: environment variables, AWS credentials file, IAM role for EC2/ECS
Falls back to DefaultCredentialsProvider if not specified or any other value

 
"static"

ipf.file-manager.s3.credentials.access-key-id

AWS access key ID for authentication when using static credentials provider.

 
"accessKey"

ipf.file-manager.s3.credentials.secret-access-key

AWS secret access key for authentication when using static credentials provider.

 
"secretAccessKey"

ipf.file-manager.s3.enabled

S3 file manager is disabled by default when the maven dependency is included. Can be enabled by setting this property to true

 
false

ipf.file-manager.s3.reader.buffer-size

Larger buffer size for better throughput with large files

 
"32kB"

ipf.file-manager.s3.region

AWS region is mandatory but will be automatically provided by the environment, see docs.aws.amazon.com/sdkref/latest/guide/feature-region.html

 
"us-east-1"

ipf.file-manager.s3.resiliency-settings.attempt-timeout

The maximum time allowed for each individual attempt before timing out. Shorter timeouts fail faster but might not allow enough time for slow operations.

 
"5s"

ipf.file-manager.s3.resiliency-settings.call-timeout

The overall timeout for the entire operation, including all retry attempts. Sets an upper bound on how long client code will wait for completion.

 
"3s"

ipf.file-manager.s3.resiliency-settings.max-attempts

Determines the maximum number of retries to be made. Note that this includes the first failed attempt.

 
5

ipf.file-manager.s3.resiliency-settings.retryable-status-codes

HTTP status codes that should trigger a retry. Typically includes server errors like 500 (Internal Server Error) and 503 (Service Unavailable).

 
[
    500,
    503
]

ipf.file-manager.s3.upload-parallelism

Controls the maximum number of parallel upload operations that can occur simultaneously. Higher values may improve throughput but increase resource usage.

 
1

Manejo de Errores

Lista de System Events

La tabla a continuación documenta el system events que puede ser planteado por S3 File Manager. Los esquemas de carga útil están documentados como Borrador 4 del esquema JSON. Utilice una herramienta como este para una representación visual de la carga útil esquemas.

Todo events contiene información básica de nivel superior y una carga útil. La información de nivel superior se representa como miembros del IPFSystemEvent tipo, y sus cargas útiles están documentadas a continuación.

El esquema para el nivel superior IPFSystemEvent el tipo es el siguiente:

Esquema de nivel superior 
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "IPF System Event",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string"
    },
    "level": {
      "type": "string",
      "enum": [ "DEBUG", "INFO", "WARN", "ERROR" ]
    },
    "createdAt": { },
    "version": {
      "$ref": "#/definitions/EventVersion"
    },
    "type": {
      "type": "string",
      "enum": [ "TECHNICAL", "FUNCTIONAL" ]
    },
    "processingContext": {
      "$ref": "#/definitions/ProcessingContext"
    },
    "source": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "payload": {
      "$ref": "#/definitions/Object"
    }
  },
  "definitions": {
    "EventVersion": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "major": {
          "type": "integer"
        },
        "minor": {
          "type": "integer"
        },
        "patch": {
          "type": "integer"
        }
      },
      "required": [ "major", "minor", "patch" ]
    },
    "ProcessingContext": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "associationId": {
          "type": "string"
        },
        "checkpoint": {
          "type": "string"
        },
        "unitOfWorkId": {
          "type": "string"
        },
        "clientRequestId": {
          "type": "string"
        },
        "processingEntity": {
          "type": "string"
        }
      }
    },
    "Object": {
      "type": "object",
      "additionalProperties": false,
      "properties": { }
    }
  }
}
Administrador de Archivos S3 System Events
Nombre Descripción Tipo Nivel Esquema de carga útil

S3Failure Event

Evento generado cuando la inicialización u operación de S3 falla.

TECHNICAL

ERROR

 
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Payload",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "message": {
      "type": "string"
    },
    "component": {
      "type": "string"
    },
    "failureType": {
      "type": "string",
      "enum": [ "CREDENTIALS_ERROR", "CLIENT_INITIALISATION_ERROR" ]
    },
    "exceptionMessage": {
      "type": "string"
    },
    "exceptionType": {
      "type": "string"
    }
  }
}

Ejemplos

Ejemplo Events

Error de inicialización del cliente S3

Descripciones de Campo
Tabla 1. Error de Inicialización del Cliente Event
Campo Descripción

nombre

Identificador único del event tipo, siempre 'S3Failure Event' para fallos relacionados con S3

nivel

Nivel de severidad del event(valores posibles: ERROR, ADVERTENCIA, INFORMACIÓN)

tipo

Clasificación del error (TÉCNICO para problemas a nivel de sistema)

fuente

Origen del event, identifica el componente que está generando el event

Campos de Metadatos

metadata.componente

Nombre del componente de la fábrica responsable de la inicialización del cliente

metadata.tipo_de_fallo

Categoría específica de la falla (CLIENT_INITIALISATION_ERROR para problemas de configuración)

metadata.región

Región de AWS especificada en la configuración

Campos de Carga

payload.message

Descripción legible por humanos del error de inicialización

payload.componente

Identificador de componente que coincide con el componente de metadatos

payload.failureType

Clasificación detallada de fallos

payload.exceptionMessage

Mensaje de error detallado que describe la falla en la inicialización

payload.exceptionType

Nombre completamente calificado de la Java excepción

detalles De Configuración Del Payload

Parámetros de configuración que llevaron a la falla de inicialización

payload.configurationDetails.endpoint

URL del endpoint de AWS S3 que fue configurado

payload.configurationDetails.region

Región de AWS especificada en la configuración
Ejemplo
{
  "name": "S3FailureEvent",
  "level": "ERROR",
  "type": "TECHNICAL",
  "source": "S3FileManager",
  "metadata": {
    "component": "S3ClientFactory",
    "failure_type": "CLIENT_INITIALISATION_ERROR",
    "region": "eu-central-1"
  },
  "payload": {
    "message": "Failed to initialise S3 client",
    "component": "S3ClientFactory",
    "failureType": "CLIENT_INITIALISATION_ERROR",
    "exceptionMessage": "Unable to initialise AWS S3 client: Invalid endpoint configuration",
    "exceptionType": "com.amazonaws. SdkClientException",
    "configurationDetails": {
      "endpoint": "https://s3.invalid-region.amazonaws.com",
      "region": "eu-central-1"
    }
  }
}

Error de credenciales de S3

Descripciones de Campo
Tabla 2. Error de credenciales Event
Campo Descripción

nombre

Identificador único del event tipo, siempre 'S3Failure Event' para fallos relacionados con S3

nivel

Nivel de severidad del event(valores posibles: ERROR, ADVERTENCIA, INFORMACIÓN)

tipo

Clasificación del error (TÉCNICO para problemas a nivel de sistema)

fuente

Origen del event, identifica el componente que está generando el event

Campos de Metadatos

metadata.componente

Nombre del componente del sistema que encontró el error

metadata.tipo_de_fallo

Categorización específica de la falla (CREDENTIALS_ERROR para problemas de autenticación)

metadata.región

Región de AWS donde se intentó la operación

metadata.bucket

Nombre del bucket S3 involucrado en la operación

Campos de Carga

payload.message

Descripción legible por humanos del error

payload.componente

Identificador de componente que coincide con el componente de metadatos

payload.failureType

Clasificación detallada de fallos

payload.exceptionMessage

Mensaje de error original del servicio AWS

payload.exceptionType

Nombre completamente calificado de la Java excepción

payload.bucket

Nombre del bucket S3 de destino

payload.key

Ruta al archivo en S3 que se estaba accediendo
Ejemplo
{
  "name": "S3FailureEvent",
  "level": "ERROR",
  "type": "TECHNICAL",
  "source": "S3FileManager",
  "metadata": {
    "component": "S3FileManager",
    "failure_type": "CREDENTIALS_ERROR",
    "region": "eu-central-1",
    "bucket": "example-bucket"
  },
  "payload": {
    "message": "Failed to authenticate with AWS S3",
    "component": "S3FileManager",
    "failureType": "CREDENTIALS_ERROR",
    "exceptionMessage": "The security token included in the request is invalid",
    "exceptionType": "com.amazonaws.services.s3.model. AmazonS3Exception",
    "bucket": "example-bucket",
    "key": "path/to/file.txt"
  }
}