S3 - Square Cloud

Blob Storage hat ein S3-kompatibles Gateway, das mit jedem S3-Client funktioniert. Das SDK gibt dir seine Zugangsdaten oder einen fertigen S3Client aus dem AWS SDK.

Beide Methoden benötigen einen API-Schlüssel. Ein mit einem Upload-Token erstellter Client erhält 403 UPLOAD_TOKEN_NOT_ALLOWED, und ein Schlüssel in einem alten Format erhält LEGACY_API_KEY.

`s3()`

s3() gibt einen S3Client aus @aws-sdk/client-s3 zurück, bereits konfiguriert mit Endpoint, Region und Zugangsdaten des Gateways sowie mit forcePathStyle: true. @aws-sdk/client-s3 ist eine optionale Peer-Abhängigkeit: Installiere sie nur, wenn du s3() verwendest. Sie wird erst bei Bedarf geladen, sodass das SDK selbst frei von Abhängigkeiten bleibt.

npm
yarn
pnpm
bun

npm install @aws-sdk/client-s3

yarn add @aws-sdk/client-s3

pnpm add @aws-sdk/client-s3

bun add @aws-sdk/client-s3

import { ListObjectsV2Command } from "@aws-sdk/client-s3";
import { SquareCloudBlob } from "@squarecloud/blob";

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
const s3 = await blob.s3();

const { Contents } = await s3.send(new ListObjectsV2Command({ Bucket: "public" }));

Buckets

Bucket	Inhalt	Zugriff
`public`	Öffentliche Objekte	Lesen und Schreiben
`private`	Private Objekte	Lesen und Schreiben
`legacy`	Objekte, die vor dem aktuellen Speicher hochgeladen wurden	Nur Lesen, Auflisten und Löschen

Wie S3-Keys auf Objekte abgebildet werden, erfährst du unter Buckets und Keys, und was das Gateway akzeptiert, unter Unterstützte Operationen.

`s3Credentials()`

Für andere S3-Clients (aws-cli, rclone, boto3, …) gibt s3Credentials() das rohe Schlüsselpaar zurück:

const credentials = await blob.s3Credentials();

Feld	Typ	Beschreibung
`access_key_id`	`string`	ID des Zugriffsschlüssels.
`secret_access_key`	`string`	Geheimer Zugriffsschlüssel.
`endpoint`	`string`	Endpoint des Gateways.
`region`	`string`	Region (`auto`).
`buckets`	`string[]`	`public`, `private` und `legacy`.
`access`	`{ read, write }`	Was das Paar darf, gemäß den Scopes des API-Schlüssels (typisiert als `boolean \| string[]`).
`expires_at`	`string \| null`	Wann der API-Schlüssel und damit das Paar abläuft; `null`, wenn er nicht abläuft.

Verwende bei jedem anderen Client Path-Style-Adressierung.

secret_access_key gewährt denselben Zugriff wie der API-Schlüssel. Behalte ihn auf dem Server und bewahre ihn wie den Schlüssel selbst auf. Das Widerrufen oder Erneuern des API-Schlüssels macht auch das Paar ungültig.

Caching

Das Paar ist pro API-Schlüssel deterministisch, daher cacht das SDK es pro Client-Instanz: s3Credentials() und s3() rufen die API einmal auf, und spätere Aufrufe verwenden das Ergebnis wieder. Ein fehlgeschlagener Aufruf wird nicht gecacht, sodass der nächste Aufruf es erneut versucht.

Die Route für Zugangsdaten akzeptiert nur 10 Anfragen pro Stunde. Erstelle einen einzigen SquareCloudBlob-Client und verwende ihn wieder, statt pro Anfrage einen neuen zu erstellen.

API-Referenz: S3 Credentials.

Dienste

Runtimes

Plattform

Fehlerbehebung

CLI

SDKs

Changelog

S3

`s3()`

Buckets

`s3Credentials()`

Caching

​s3()

​Buckets

​s3Credentials()

​Caching

`s3()`

Buckets

`s3Credentials()`

Caching