Vue d'ensemble

L’API de stockage de StudioCMS offre une méthode unifiée pour gérer et interagir avec différents systèmes de stockage. Elle simplifie la complexité de ces systèmes, permettant ainsi aux développeurs de travailler avec une interface cohérente quelle que soit la technologie sous-jacente.

Son fonctionnement

L’API de stockage est conçue pour être flexible et extensible. Elle prend en charge plusieurs systèmes de stockage, notamment les systèmes de fichiers locaux, les services de stockage cloud et les bases de données. Les développeurs peuvent choisir le système de stockage le mieux adapté à leurs besoins et passer facilement de l’un à l’autre sans modifier le code de leur application.

Modules d’extension de gestionnaire

L’API de stockage utilise des modules d’extension de gestionnaire pour gérer différents systèmes de stockage. Chaque module d’extension de gestionnaire implémente un système de stockage spécifique et fournit des méthodes pour les opérations courantes telles que la lecture, l’écriture et la suppression de fichiers.

Un exemple de gestionnaire intégré à StudioCMS est le gestionnaire no-op, qui n’effectue aucune opération et indique à StudioCMS de ne pas activer ses fonctionnalités de stockage.

Exemple de gestionnaire sans opération

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 UrlMappingServiceDefinition
import 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';

/**
 * A No-Op Storage Service that implements the StorageApiBuilderDefinition interface.
 *
 * This service provides placeholder implementations for storage API endpoints,
 * returning a 501 Not Implemented response for both POST and PUT requests.
 *
 * @typeParam C - The context type.
 * @typeParam R - The response type.
 */
export default class 
class NoOpStorageService<C, R>
A No-Op Storage Service that implements the StorageApiBuilderDefinition interface.
This service provides placeholder implementations for storage API endpoints,
returning a 501 Not Implemented response for both POST and PUT requests.
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 UrlMappingServiceDefinition
import 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 UrlMappingServiceDefinition
import 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());
    }
}

Configuration d’un gestionnaire

Pour configurer un gestionnaire de stockage dans StudioCMS, vous devez spécifier le module d’extension de gestionnaire souhaité dans votre fichier de configuration StudioCMS. Pour ce faire, vous devez installer le paquet du module d’extension de gestionnaire, puis l’ajouter à la propriété storageManager dans votre fichier studiocms.config.*.

import { 
function defineStudioCMSConfig(config: StudioCMSOptions): StudioCMSOptions
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.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';

export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig } from "studiocms/config";
import 
function s3Storage(): StudioCMSStorageManager
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.
@returns ― A configured storage manager instance that integrates
S3 storage capabilities with StudioCMS.
@example 
import { studiocmsS3Storage } from '@studiocms/s3-storage';

const s3Storage = studiocmsS3Storage();
s3Storage from '@studiocms/s3-storage';

export default 
function defineStudioCMSConfig(config: StudioCMSOptions): StudioCMSOptions
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.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';

export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig({
    
StudioCMSOptions.storageManager?: StudioCMSStorageManager
Storage Manager Configuration
storageManager: 
function s3Storage(): StudioCMSStorageManager
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.
@returns ― A configured storage manager instance that integrates
S3 storage capabilities with StudioCMS.
@example 
import { studiocmsS3Storage } from '@studiocms/s3-storage';

const s3Storage = studiocmsS3Storage();
s3Storage(),
    // autres options de configuration
})

Pour connaître les modules d’extension de gestionnaire de stockage disponibles, consultez le catalogue des paquets.