Descripción General
La API de almacenamiento en StudioCMS proporciona una forma unificada de gestionar e interactuar con varios backends de almacenamiento. Abstrae las complejidades de los diferentes sistemas de almacenamiento, permitiendo a los desarrolladores trabajar con una interfaz consistente independientemente de la tecnología subyacente.
Cómo funciona
Sección titulada «Cómo funciona»La API de almacenamiento está diseñada para ser flexible y extensible. Soporta múltiples backends de almacenamiento, incluyendo sistemas de archivos locales, servicios de almacenamiento en la nube y bases de datos. Los desarrolladores pueden elegir el backend de almacenamiento que mejor se adapte a sus necesidades y cambiar fácilmente entre ellos sin modificar el código de su aplicación.
Plugins de gestión
Sección titulada «Plugins de gestión»La API de almacenamiento utiliza plugins de gestión para manejar diferentes backends de almacenamiento. Cada plugin de gestión implementa un sistema de almacenamiento específico y proporciona métodos para operaciones comunes como leer, escribir y eliminar archivos.
Un ejemplo de un gestor integrado en StudioCMS es el gestor no-op, que no realiza ninguna operación e indica a StudioCMS que no active ninguna de sus funciones de almacenamiento.
Ejemplo del gestor No-op
Sección titulada «Ejemplo del gestor No-op»import type { type AuthorizationType = "locals" | "headers"
Authorization Type.
This type defines the possible authorization types
that can be used in storage manager API requests.
AuthorizationType, interface ContextDriverDefinition<C, R>
Context Driver Definition interface.
This interface defines the structure and methods for a context driver,
including parsing the context, building responses, and handling endpoints.
ContextDriverDefinition, type StorageAPIEndpointFn<C, R> = (context: C) => Promise<R>
Storage API Endpoint Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
StorageAPIEndpointFn, interface StorageApiBuilderDefinition<C, R>
Storage API Builder Definition interface.
This interface defines the structure and methods for building storage API endpoints,
including handling POST and PUT requests.
StorageApiBuilderDefinition, (alias) interface UrlMappingServiceDefinitionimport UrlMappingServiceDefinition
URL Mapping Service Definition interface.
This interface defines the structure and methods for the URL Mapping Service,
which manages the mapping between storage file identifiers and their corresponding URLs.
UrlMappingServiceDefinition,} from 'studiocms/storage-manager/definitions';
/** * Un servicio No-Op (sin operación) que implementa la interfaz StorageApiBuilderDefinition. * * Este servicio proporciona implementaciones placeholder para los endpoints de la API de almacenamiento, * devolviendo una respuesta 501 No Implementado tanto para solicitudes POST como PUT. * * @typeParam C - El tipo de contexto. * @typeParam R - El tipo de respuesta. */
export default class class NoOpStorageService<C, R>
Un servicio No-Op (sin operación) que implementa la interfaz StorageApiBuilderDefinition.
Este servicio proporciona implementaciones placeholder para los endpoints de la API de almacenamiento,
devolviendo una respuesta 501 No Implementado tanto para solicitudes POST como PUT.
NoOpStorageService<function (type parameter) C in NoOpStorageService<C, R>
C, function (type parameter) R in NoOpStorageService<C, R>
R> implements interface StorageApiBuilderDefinition<C, R>
Storage API Builder Definition interface.
This interface defines the structure and methods for building storage API endpoints,
including handling POST and PUT requests.
StorageApiBuilderDefinition<function (type parameter) C in NoOpStorageService<C, R>
C, function (type parameter) R in NoOpStorageService<C, R>
R> { NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver: interface ContextDriverDefinition<C, R>
Context Driver Definition interface.
This interface defines the structure and methods for a context driver,
including parsing the context, building responses, and handling endpoints.
ContextDriverDefinition<function (type parameter) C in NoOpStorageService<C, R>
C, function (type parameter) R in NoOpStorageService<C, R>
R>; NoOpStorageService<C, R>.urlMappingService: UrlMappingServiceDefinition
urlMappingService: (alias) interface UrlMappingServiceDefinitionimport UrlMappingServiceDefinition
URL Mapping Service Definition interface.
This interface defines the structure and methods for the URL Mapping Service,
which manages the mapping between storage file identifiers and their corresponding URLs.
UrlMappingServiceDefinition;
constructor( driver: ContextDriverDefinition<C, R>
driver: interface ContextDriverDefinition<C, R>
Context Driver Definition interface.
This interface defines the structure and methods for a context driver,
including parsing the context, building responses, and handling endpoints.
ContextDriverDefinition<function (type parameter) C in NoOpStorageService<C, R>
C, function (type parameter) R in NoOpStorageService<C, R>
R>, urlMappingService: UrlMappingServiceDefinition
urlMappingService: (alias) interface UrlMappingServiceDefinitionimport UrlMappingServiceDefinition
URL Mapping Service Definition interface.
This interface defines the structure and methods for the URL Mapping Service,
which manages the mapping between storage file identifiers and their corresponding URLs.
UrlMappingServiceDefinition ) { this.NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver = driver: ContextDriverDefinition<C, R>
driver; this.NoOpStorageService<C, R>.urlMappingService: UrlMappingServiceDefinition
urlMappingService = urlMappingService: UrlMappingServiceDefinition
urlMappingService; }
#sharedResponse() { return { data: { error: string;}
data: { error: string
error: 'noStorageConfigured' }, status: number
status: 501 }; }
NoOpStorageService<C, R>.getPOST(_?: AuthorizationType): StorageAPIEndpointFn<C, R>
getPOST(_: AuthorizationType | undefined
_?: type AuthorizationType = "locals" | "headers"
Authorization Type.
This type defines the possible authorization types
that can be used in storage manager API requests.
AuthorizationType): type StorageAPIEndpointFn<C, R> = (context: C) => Promise<R>
Storage API Endpoint Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
StorageAPIEndpointFn<function (type parameter) C in NoOpStorageService<C, R>
C, function (type parameter) R in NoOpStorageService<C, R>
R> { return this.NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver.ContextDriverDefinition<C, R>.handleEndpoint(contextHandler: ContextHandler): ContextHandlerFn<C, R>
handleEndpoint(async () => this.#sharedResponse()); }
NoOpStorageService<C, R>.getPUT(_?: AuthorizationType): StorageAPIEndpointFn<C, R>
getPUT(_: AuthorizationType | undefined
_?: type AuthorizationType = "locals" | "headers"
Authorization Type.
This type defines the possible authorization types
that can be used in storage manager API requests.
AuthorizationType): type StorageAPIEndpointFn<C, R> = (context: C) => Promise<R>
Storage API Endpoint Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
StorageAPIEndpointFn<function (type parameter) C in NoOpStorageService<C, R>
C, function (type parameter) R in NoOpStorageService<C, R>
R> { return this.NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver.ContextDriverDefinition<C, R>.handleEndpoint(contextHandler: ContextHandler): ContextHandlerFn<C, R>
handleEndpoint(async () => this.#sharedResponse()); }}Configurando un gestor
Sección titulada «Configurando un gestor»Para configurar un gestor de almacenamiento en StudioCMS, debes especificar el plugin de gestión deseado en tu archivo de configuración de StudioCMS. Para hacerlo, debes instalar el paquete del plugin de gestión y luego añadirlo a la propiedad storageManager en tu archivo studiocms.config.*.
import { function defineStudioCMSConfig(config: StudioCMSOptions): { readonly dbStartPage?: boolean | undefined; readonly verbose?: boolean | undefined; readonly logLevel?: "All" | "Fatal" | "Error" | "Warning" | "Info" | "Debug" | "Trace" | "None" | undefined; readonly db?: { readonly dialect?: "libsql" | "postgres" | "mysql" | undefined; } | undefined; readonly plugins?: { readonly identifier: string; readonly name: string; readonly studiocmsMinimumVersion?: string | undefined; readonly requires?: readonly string[] | undefined; readonly hooks: { "studiocms:astro-config"?: ((args: { readonly logger: AstroIntegrationLogger; readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>; }) => Promise<void>) | ((args: { readonly logger: AstroIntegrationLogger; readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>; }) => void) | undefined; "studiocms:auth"?: ((args: { readonly logger: AstroIntegrationLogger; readonly setAuthService: (args: { oAuthProvider: { readonly name: string; readonly formattedName: string; readonly svg: string; readonly endpointPath: string; readonly requiredEnvVariables?: readonly string[] | undefined; }; }) => Promise<void>; }) => Promise<void>) | ((args: { readonly logger: AstroIntegrationLogger; readonly setAuthService: (args: { oAuthProvider: { readonly name: string; readonly formattedName: string; readonly svg: string; readonly endpointPath: string; readonly requiredEnvVariables?: readonly string[] | undefined; }; }) => Promise<void>; }) => void) | undefined; "studiocms:dashboard"?: ((args: { readonly logger: AstroIntegrationLogger; readonly setDashboard: (args: { translations: { [x: string]: { [x: string]: { [x: string]: string; }; }; }; dashboardGridItems?: readonly { readonly name: string; readonly span: 1 | 2 | 3; readonly variant: "default" | "filled"; readonly requiresPermission?: "owner" | "admin" | "editor" | "visitor" | undefined; readonly header?: { readonly title: string; readonly icon?: "heroicons:academic-cap" | "heroicons:academic-cap-16-solid" | "heroicons:academic-cap-20-solid" | "heroicons:academic-cap-solid" | "heroicons:adjustments-horizontal" | "heroicons:adjustments-horizontal-16-solid" | "heroicons:adjustments-horizontal-20-solid" | "heroicons:adjustments-horizontal-solid" | "heroicons:adjustments-vertical" | "heroicons:adjustments-vertical-16-solid" | "heroicons:adjustments-vertical-20-solid" | "heroicons:adjustments-vertical-solid" | "heroicons:archive-box" | "heroicons:archive-box-16-solid" | "heroicons:archive-box-20-solid" | "heroicons:archive-box-arrow-down" | "heroicons:archive-box-arrow-down-16-solid" | "heroicons:archive-box-arrow-down-20-solid" | "heroicons:archive-box-arrow-down-solid" | "heroicons:archive-box-solid" | "heroicons:archive-box-x-mark" | "heroicons:archive-box-x-mark-16-solid" | "heroicons:archive-box-x-mark-20-solid" | "heroicons:archive-box-x-mark-solid" | "heroicons:arrow-down" | "heroicons:arrow-down-16-solid" | "heroicons:arrow-down-20-solid" | "heroicons:arrow-down-circle" | "heroicons:arrow-down-circle-16-solid" | "heroicons:arrow-down-circle-20-solid" | "heroicons:arrow-down-circle-solid" | "heroicons:arrow-down-left" | "heroicons:arrow-down-left-16-solid" | "heroicons:arrow-down-left-20-solid" | "heroicons:arrow-down-left-solid" | "heroicons:arrow-down-on-square" | "heroicons:arrow-down-on-square-16-solid" | "heroicons:arrow-down-on-square-20-solid" | "heroicons:arrow-down-on-square-solid" | "heroicons:arrow-down-on-square-stack" | "heroicons:arrow-down-on-square-stack-16-solid" | "heroicons:arrow-down-on-square-stack-20-solid" | "heroicons:arrow-down-on-square-stack-solid" | "heroicons:arrow-down-right" | "heroicons:arrow-down-right-16-solid" | "heroicons:arrow-down-right-20-solid" | "heroicons:arrow-down-right-solid" | "heroicons:arrow-down-solid" | "heroicons:arrow-down-tray" | "heroicons:arrow-down-tray-16-solid" | "heroicons:arrow-down-tray-20-solid" | "heroicons:arrow-down-tray-solid" ...
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.
StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.
Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
defineStudioCMSConfig } from "studiocms/config";import function almacenamientoS3(): StudioCMSStorageManagerDef
Creates and configures a StudioCMS S3 Storage Manager plugin.
This function initializes the S3 storage integration for StudioCMS by defining
a storage manager plugin with the necessary configuration and hooks.
almacenamientoS3 from '@studiocms/s3-storage';
export default function defineStudioCMSConfig(config: StudioCMSOptions): { readonly dbStartPage?: boolean | undefined; readonly verbose?: boolean | undefined; readonly logLevel?: "All" | "Fatal" | "Error" | "Warning" | "Info" | "Debug" | "Trace" | "None" | undefined; readonly db?: { readonly dialect?: "libsql" | "postgres" | "mysql" | undefined; } | undefined; readonly plugins?: { readonly identifier: string; readonly name: string; readonly studiocmsMinimumVersion?: string | undefined; readonly requires?: readonly string[] | undefined; readonly hooks: { "studiocms:astro-config"?: ((args: { readonly logger: AstroIntegrationLogger; readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>; }) => Promise<void>) | ((args: { readonly logger: AstroIntegrationLogger; readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>; }) => void) | undefined; "studiocms:auth"?: ((args: { readonly logger: AstroIntegrationLogger; readonly setAuthService: (args: { oAuthProvider: { readonly name: string; readonly formattedName: string; readonly svg: string; readonly endpointPath: string; readonly requiredEnvVariables?: readonly string[] | undefined; }; }) => Promise<void>; }) => Promise<void>) | ((args: { readonly logger: AstroIntegrationLogger; readonly setAuthService: (args: { oAuthProvider: { readonly name: string; readonly formattedName: string; readonly svg: string; readonly endpointPath: string; readonly requiredEnvVariables?: readonly string[] | undefined; }; }) => Promise<void>; }) => void) | undefined; "studiocms:dashboard"?: ((args: { readonly logger: AstroIntegrationLogger; readonly setDashboard: (args: { translations: { [x: string]: { [x: string]: { [x: string]: string; }; }; }; dashboardGridItems?: readonly { readonly name: string; readonly span: 1 | 2 | 3; readonly variant: "default" | "filled"; readonly requiresPermission?: "owner" | "admin" | "editor" | "visitor" | undefined; readonly header?: { readonly title: string; readonly icon?: "heroicons:academic-cap" | "heroicons:academic-cap-16-solid" | "heroicons:academic-cap-20-solid" | "heroicons:academic-cap-solid" | "heroicons:adjustments-horizontal" | "heroicons:adjustments-horizontal-16-solid" | "heroicons:adjustments-horizontal-20-solid" | "heroicons:adjustments-horizontal-solid" | "heroicons:adjustments-vertical" | "heroicons:adjustments-vertical-16-solid" | "heroicons:adjustments-vertical-20-solid" | "heroicons:adjustments-vertical-solid" | "heroicons:archive-box" | "heroicons:archive-box-16-solid" | "heroicons:archive-box-20-solid" | "heroicons:archive-box-arrow-down" | "heroicons:archive-box-arrow-down-16-solid" | "heroicons:archive-box-arrow-down-20-solid" | "heroicons:archive-box-arrow-down-solid" | "heroicons:archive-box-solid" | "heroicons:archive-box-x-mark" | "heroicons:archive-box-x-mark-16-solid" | "heroicons:archive-box-x-mark-20-solid" | "heroicons:archive-box-x-mark-solid" | "heroicons:arrow-down" | "heroicons:arrow-down-16-solid" | "heroicons:arrow-down-20-solid" | "heroicons:arrow-down-circle" | "heroicons:arrow-down-circle-16-solid" | "heroicons:arrow-down-circle-20-solid" | "heroicons:arrow-down-circle-solid" | "heroicons:arrow-down-left" | "heroicons:arrow-down-left-16-solid" | "heroicons:arrow-down-left-20-solid" | "heroicons:arrow-down-left-solid" | "heroicons:arrow-down-on-square" | "heroicons:arrow-down-on-square-16-solid" | "heroicons:arrow-down-on-square-20-solid" | "heroicons:arrow-down-on-square-solid" | "heroicons:arrow-down-on-square-stack" | "heroicons:arrow-down-on-square-stack-16-solid" | "heroicons:arrow-down-on-square-stack-20-solid" | "heroicons:arrow-down-on-square-stack-solid" | "heroicons:arrow-down-right" | "heroicons:arrow-down-right-16-solid" | "heroicons:arrow-down-right-20-solid" | "heroicons:arrow-down-right-solid" | "heroicons:arrow-down-solid" | "heroicons:arrow-down-tray" | "heroicons:arrow-down-tray-16-solid" | "heroicons:arrow-down-tray-20-solid" | "heroicons:arrow-down-tray-solid" ...
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.
StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.
Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
defineStudioCMSConfig({ storageManager?: { readonly identifier: string; readonly name: string; readonly studiocmsMinimumVersion?: string | undefined | undefined; readonly requires?: readonly string[] | undefined; readonly hooks: { "studiocms:astro-config"?: ((args: { readonly logger: AstroIntegrationLogger; readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>; }) => Promise<void>) | ((args: { readonly logger: AstroIntegrationLogger; readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>; }) => void) | undefined; "studiocms:auth"?: ((args: { readonly logger: AstroIntegrationLogger; readonly setAuthService: (args: { oAuthProvider: { readonly name: string; readonly formattedName: string; readonly svg: string; readonly endpointPath: string; readonly requiredEnvVariables?: readonly string[] | undefined; }; }) => Promise<void>; }) => Promise<void>) | ((args: { readonly logger: AstroIntegrationLogger; readonly setAuthService: (args: { oAuthProvider: { readonly name: string; readonly formattedName: string; readonly svg: string; readonly endpointPath: string; readonly requiredEnvVariables?: readonly string[] | undefined; }; }) => Promise<void>; }) => void) | undefined; "studiocms:dashboard"?: ((args: { readonly logger: AstroIntegrationLogger; readonly setDashboard: (args: { translations: { [x: string]: { [x: string]: { [x: string]: string; }; }; }; dashboardGridItems?: readonly { readonly name: string; readonly span: 1 | 2 | 3; readonly variant: "default" | "filled"; readonly requiresPermission?: "owner" | "admin" | "editor" | "visitor" | undefined; readonly header?: { readonly title: string; readonly icon?: "heroicons:academic-cap" | "heroicons:academic-cap-16-solid" | "heroicons:academic-cap-20-solid" | "heroicons:academic-cap-solid" | "heroicons:adjustments-horizontal" | "heroicons:adjustments-horizontal-16-solid" | "heroicons:adjustments-horizontal-20-solid" | "heroicons:adjustments-horizontal-solid" | "heroicons:adjustments-vertical" | "heroicons:adjustments-vertical-16-solid" | "heroicons:adjustments-vertical-20-solid" | "heroicons:adjustments-vertical-solid" | "heroicons:archive-box" | "heroicons:archive-box-16-solid" | "heroicons:archive-box-20-solid" | "heroicons:archive-box-arrow-down" | "heroicons:archive-box-arrow-down-16-solid" | "heroicons:archive-box-arrow-down-20-solid" | "heroicons:archive-box-arrow-down-solid" | "heroicons:archive-box-solid" | "heroicons:archive-box-x-mark" | "heroicons:archive-box-x-mark-16-solid" | "heroicons:archive-box-x-mark-20-solid" | "heroicons:archive-box-x-mark-solid" | "heroicons:arrow-down" | "heroicons:arrow-down-16-solid" | "heroicons:arrow-down-20-solid" | "heroicons:arrow-down-circle" | "heroicons:arrow-down-circle-16-solid" | "heroicons:arrow-down-circle-20-solid" | "heroicons:arrow-down-circle-solid" | "heroicons:arrow-down-left" | "heroicons:arrow-down-left-16-solid" | "heroicons:arrow-down-left-20-solid" | "heroicons:arrow-down-left-solid" | "heroicons:arrow-down-on-square" | "heroicons:arrow-down-on-square-16-solid" | "heroicons:arrow-down-on-square-20-solid" | "heroicons:arrow-down-on-square-solid" | "heroicons:arrow-down-on-square-stack" | "heroicons:arrow-down-on-square-stack-16-solid" | "heroicons:arrow-down-on-square-stack-20-solid" | "heroicons:arrow-down-on-square-stack-solid" | "heroicons:arrow-down-right" | "heroicons:arrow-down-right-16-solid" | "heroicons:arrow-down-right-20-solid" | "heroicons:arrow-down-right-solid" | "heroicons:arrow-down-solid" | "heroicons:arrow-down-tray" | "heroicons:arrow-down-tray-16-solid" | "heroicons:arrow-down-tray-20-solid" | "heroicons:arrow-down-tray-solid" | "heroicons:arrow-left" | "heroicons:arrow-left-16-solid" | "heroicons:arrow-left-20-solid" | "heroicons:arrow-left-circle" | "heroicons:arrow-left-circle-16-solid" | "heroicons:arrow-left-circle-20-solid" | "heroicons:arrow-left-circle-solid" | "heroicons:arrow-left-end-on-rectangle" | "heroicons:arrow-left-end-on-rectangle-16-solid" | "heroicons:arrow-left-end-on-rectangle-20-solid" | "heroicons:arrow-left-end-on-rectangle-solid" | "heroicons:arrow-left-on-rectangle" | "heroicons:arrow-left-on-rectangle-20-solid" | "heroicons:arrow-left-on-rectangle-solid" ...
storageManager: function almacenamientoS3(): StudioCMSStorageManagerDef
Creates and configures a StudioCMS S3 Storage Manager plugin.
This function initializes the S3 storage integration for StudioCMS by defining
a storage manager plugin with the necessary configuration and hooks.
almacenamientoS3(), // otras opciones de configuración})Para conocer los plugins de gestión de almacenamiento disponibles, consulta el Catálogo de paquetes.