diff --git a/src/content/docs/fr/storage-api/api-endpoint.mdx b/src/content/docs/fr/storage-api/api-endpoint.mdx new file mode 100644 index 00000000..b8dc4996 --- /dev/null +++ b/src/content/docs/fr/storage-api/api-endpoint.mdx @@ -0,0 +1,140 @@ +--- +i18nReady: true +title: Point de terminaison de l'API +description: Découvrez les points de terminaison de l'API disponibles dans l'API de stockage de StudioCMS. +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 4 +sidebar: + order: 3 + badge: + text: NOUVEAU + variant: success +--- + +import ReadMore from '~/components/ReadMore.astro'; +import { Aside } from '@astrojs/starlight/components'; + +L'API de stockage expose des points de terminaison accessibles via des requêtes HTTP. Les sections suivantes décrivent les points de terminaison disponibles et leur utilisation. + + + +### Méthode : PUT + +Pour télécharger ou mettre à jour un fichier dans le système de stockage, vous pouvez utiliser la méthode `PUT` dans le point de terminaison `/studiocms_api/storage/manager`. + +```http title="API de stockage - PUT /studiocms_api/storage/manager" +PUT /studiocms_api/storage/manager HTTP/1.1 +Host: example.com +Content-Type: application/octet-stream +Accept: application/json +Headers: + x-storage-key: my-file.txt + + +``` + +#### Réponse de succès + +```http title="API de stockage - PUT Réponse de succès" +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "message": "string", + "key": "string" +} +``` + +#### Réponse d'erreur + +```http title="API de stockage - PUT Réponse d'erreur" +HTTP/1.1 4XX/5XX Error +Content-Type: application/json + +{ + "error": "string" +} +``` + +### Méthode : POST + +```http title="API de stockage - POST /studiocms_api/storage/manager" +POST /studiocms_api/storage/manager HTTP/1.1 +Host: example.com +Content-Type: application/json +Accept: application/json + +{ + "action": "resolveUrl | publicUrl | upload | list | delete | rename | download | cleanup | mappings | test", + ...paramètres supplémentaires reposant sur l'action... +} +``` + +#### Actions + +- `resolveUrl` + - **Paramètres :** `{ identifier: string }` + - **Réponse :** [`UrlMetadata`](#urlmetadata) +- `publicUrl` + - **Paramètres :** `{ key: string }` + - **Réponse :** [`UrlMetadata`](#urlmetadata) `& { identifier: string }` +- `upload` + - **Paramètres :** `{ key: string, contentType: string }` + - **Réponse :** `{ url: string, key: string }` +- `list` + - **Paramètres :** `{ prefix?: string, key?: string }` + - **Réponse :** `{ files:` [`File[]`](#file) `}` +- `delete` + - **Paramètres :** `{ key: string }` + - **Réponse :** `{ success: boolean }` +- `rename` + - **Paramètres :** `{ key: string, newKey: string }` + - **Réponse :** `{ success: boolean, newKey: string }` +- `download` + - **Paramètres :** `{ key: string }` + - **Réponse :** `{ url: string }` +- `cleanup` + - **Paramètres :** `N/A` + - **Réponse :** `{ deletedCount: number }` +- `mappings` + - **Paramètres :** `N/A` + - **Réponse :** `{ mappings:` [`UrlMetadata[]`](#urlmetadata) `}` +- `test` + - **Paramètres :** `N/A` + - **Réponse :** `{ success: boolean, message: string, provider: string }` + +#### Réponse d'erreur + +```http title="API de stockage - POST Réponse d'erreur" +HTTP/1.1 4XX/5XX Error +Content-Type: application/json + +{ + "error": "string" +} +``` + +## Types + +### UrlMetadata + +```ts +export interface UrlMetadata { + url: string; + isPermanent: boolean; + expiresAt?: number; // Horodatage Unix en ms +} +``` + +### File + +```ts +export interface File { + key: string | undefined; + size: number | undefined; + lastModified: Date | undefined; +} +``` diff --git a/src/content/docs/fr/storage-api/index.mdx b/src/content/docs/fr/storage-api/index.mdx new file mode 100644 index 00000000..5215df4e --- /dev/null +++ b/src/content/docs/fr/storage-api/index.mdx @@ -0,0 +1,93 @@ +--- +i18nReady: true +title: Vue d'ensemble +description: Découvrez l'API de stockage de StudioCMS +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 4 +sidebar: + order: 1 + badge: + text: NOUVEAU + variant: success +--- + +import ReadMore from '~/components/ReadMore.astro'; +import { Aside } from '@astrojs/starlight/components'; + +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 + +```ts twoslash title="NoOpStorageService.ts" +import type { + AuthorizationType, + ContextDriverDefinition, + StorageAPIEndpointFn, + StorageApiBuilderDefinition, + 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 NoOpStorageService implements + StorageApiBuilderDefinition { + driver: ContextDriverDefinition; + urlMappingService: UrlMappingServiceDefinition; + + constructor( + driver: ContextDriverDefinition, + urlMappingService: UrlMappingServiceDefinition + ) { + this.driver = driver; + this.urlMappingService = urlMappingService; + } + + #sharedResponse() { + return { data: { error: 'noStorageConfigured' }, status: 501 }; + } + + getPOST(_?: AuthorizationType): StorageAPIEndpointFn { + return this.driver.handleEndpoint(async () => this.#sharedResponse()); + } + + getPUT(_?: AuthorizationType): StorageAPIEndpointFn { + return this.driver.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.*`. + +```ts twoslash title="studiocms.config.mjs" {5} +import { defineStudioCMSConfig } from "studiocms/config"; +import s3Storage from '@studiocms/s3-storage'; + +export default defineStudioCMSConfig({ + storageManager: s3Storage(), + // autres options de configuration +}) +``` + + +Pour connaître les modules d'extension de gestionnaire de stockage disponibles, consultez le [catalogue des paquets](/fr/package-catalog#gestionnaires-de-stockage). + diff --git a/src/content/docs/fr/storage-api/javascript-helpers.mdx b/src/content/docs/fr/storage-api/javascript-helpers.mdx new file mode 100644 index 00000000..1e2a202e --- /dev/null +++ b/src/content/docs/fr/storage-api/javascript-helpers.mdx @@ -0,0 +1,55 @@ +--- +i18nReady: true +title: Fonctions d'assistance JavaScript +description: Découvrez les fonctions d'assistance JavaScript disponibles dans l'API de stockage de StudioCMS. +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 4 +sidebar: + order: 2 + badge: + text: NOUVEAU + variant: success +--- + +import ReadMore from '~/components/ReadMore.astro'; +import { Aside } from '@astrojs/starlight/components'; + +L'API de stockage de StudioCMS fournit plusieurs fonctions d'assistance JavaScript pour faciliter l'interaction avec les systèmes de stockage. Ces fonctions d'assistance simplifient des tâches telles que la résolution des identifiants et des clés de stockage, ainsi que la fourniture de définitions de type pour une sûreté du typage et une complétion de code améliorées. + +## Fonctions d'assistance JavaScript + +```ts twoslash title="exemple-api-stockage.ts" +import { + resolveStorageIdentifier, + resolveStorageKey, +} from 'studiocms/storage-api'; + +const storageIdentifier = await resolveStorageIdentifier('storage-file://my-file.txt', { + baseUrl: 'https://example.com/', // Utilisez la valeur de `site` depuis "astro:config/server" +}); + +const storageKey = await resolveStorageKey('my-file.txt', { + baseUrl: 'https://example.com/', // Utilisez la valeur de `site` depuis "astro:config/server" +}); +``` + +## Types JavaScript + +```ts twoslash title="types-api-stockage.ts" +import type { + ContextJsonBody, + AuthorizationType, + ParsedContext, + UrlMetadata, + UrlMapping, + ContextHandler, + ContextHandlerFn, + ContextDriverDefinition, + StorageAPIEndpointFn, + StorageApiBuilderDefinition, + UrlMappingDatabaseDefinition, + UrlMappingServiceDefinition, + APICoreDefinition +} from 'studiocms/storage-api'; +```