S3 互換性

Blob Storage は https://s3-blob.squarecloud.app で S3 API に対応しています。カスタム endpoint を設定できるツールであれば動作します: aws-cli、boto3、AWS SDK for JavaScript、rclone、Cyberduck、およびほとんどのバックアップツールです。

認証情報

S3 ツールはアクセスキーのペアでリクエストに署名します。ペアは S3 認証情報から取得します。

curl https://blob.squarecloud.app/v1/s3/credentials \
  --header 'Authorization: YOUR_API_KEY'

このペアは API キーから導出されます。個別に管理する必要はありません。キーを取り消したり再生成したりすると、ペアにも同じことが起こり、ペアはキーと同じスコープを持ちます。blob:read のみを持つキーからは読み取り専用のペアが得られます。 API キーが変わらない限りペアも変わらないため、一度取得してシークレットマネージャーまたは環境変数に保管してください。起動のたびにこのルートを呼び出さないでください: 受け付けるのは 1 時間に 10 リクエストです。

設定	値
Endpoint	`https://s3-blob.squarecloud.app`
リージョン	`auto`
アドレス指定	パス形式 (`https://s3-blob.squarecloud.app/<bucket>/<key>`)
署名	AWS Signature Version 4

バケット

アカウントからは 3 つの固定バケットが見えます。バケットの作成や削除はできません。

バケット	内容	アクセス
`public`	公開ファイル。`https://blob.squarecloud.dev/pub/<user_id>/<key>` で配信されます	読み取りと書き込み
`private`	公開 URL のないプライベートファイル	読み取りと書き込み
`legacy`	2026年9月のアップデート以前にアップロードされたレガシーファイル	読み取り、一覧表示、削除

public または private バケット内のキーは、ユーザー id を含まないオブジェクトのパスです。public バケット内の images/logo.png は、REST API 上のオブジェクト pub/<user_id>/images/logo.png にあたります。S3 経由で書き込んだファイルは REST API とダッシュボードに表示され、その逆も同様です。

設定

aws configure set aws_access_key_id SQ2_...
aws configure set aws_secret_access_key ...
aws configure set region auto

aws s3 cp ./logo.png s3://public/images/logo.png \
  --endpoint-url https://s3-blob.squarecloud.app
aws s3 ls s3://public/images/ --endpoint-url https://s3-blob.squarecloud.app

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3-blob.squarecloud.app",
    aws_access_key_id="SQ2_...",
    aws_secret_access_key="...",
    region_name="auto",
    config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)

s3.upload_file("report.pdf", "private", "reports/2026/report.pdf")
url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "private", "Key": "reports/2026/report.pdf"},
    ExpiresIn=3600,
)

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3-blob.squarecloud.app",
  region: "auto",
  forcePathStyle: true,
  credentials: { accessKeyId: "SQ2_...", secretAccessKey: "..." },
});

await s3.send(new PutObjectCommand({
  Bucket: "public",
  Key: "images/logo.png",
  Body: buffer,
  ContentType: "image/png",
}));

[squarecloud]
type = s3
provider = Other
access_key_id = SQ2_...
secret_access_key = ...
endpoint = https://s3-blob.squarecloud.app
region = auto
force_path_style = true

boto3 で署名付き URL を生成するには signature_version="s3v4" が必要です。指定しないと、generate_presigned_url は古い SigV2 で署名し、ゲートウェイはそれを受け付けません。署名付き URL の有効期間は最大 7 日 (604800 秒) です。

ゲートウェイのレスポンスがエッジでキャッシュされることはありません。署名付き URL は、有効期限が切れた時点、API キーが取り消された時点、またはオブジェクトが削除された時点で、ただちに機能しなくなります。

サポートされる操作

分類	操作
バケット	`ListBuckets`、`HeadBucket`、`GetBucketLocation`。既存のバケットに対する `CreateBucket` は成功します。`DeleteBucket` はバケットにファイルがある間は `BucketNotEmpty` を返します。
一覧表示	`ListObjects` と `ListObjectsV2`。`delimiter`、`prefix`、`encoding-type=url` に対応します。
オブジェクト	`HeadObject`、`GetObject` (`Range`、`If-Match`、`If-None-Match`、`If-Modified-Since` に対応)、`PutObject` (1 リクエストで最大 100 MB)、`CopyObject` (`COPY` と `REPLACE` のメタデータディレクティブ)、`DeleteObject`、`DeleteObjects` (最大 1000 キー)。
マルチパート	`CreateMultipartUpload`、`UploadPart` (パートあたり 5 MB〜80 MB。最後のパートを除く)、`UploadPartCopy`、`CompleteMultipartUpload`、`AbortMultipartUpload`、`ListParts`、`ListMultipartUploads`。オブジェクトは最大 10 GiB です。
整合性	`Content-MD5` は、`x-amz-checksum-*` ヘッダーが同時に送信された場合でも常に検証されます。`x-amz-checksum-crc32`、`-sha1`、`-sha256` も検証され、一致しない場合は `BadDigest` が返されます。`crc32c` と `crc64nvme` は検証なしで受け付けられます。`aws-chunked` の本文に対応しています。
互換性	`GetBucketVersioning`、`GetBucketAcl`、`GetObjectAcl` およびタグの読み取りは固定値を返すため、これらを確認するツールも動作し続けます。

バケットポリシー、CORS、ライフサイクル、ウェブサイト、暗号化、オブジェクトロック、バージョン、ログ記録、通知、レプリケーション、ACL とタグの書き込み、partNumber による GET、ブラウザの POST フォームによるアップロードは 501 NotImplemented を返します。ライフサイクルルールにはアカウント設定を使用してください。

キー

キーはリテラルなパスです。キーの長さは約 1000 バイトまでです: 1024 バイトの上限にはアカウントのプレフィックスも含まれます。それより長いキーには KeyTooLongError が返され、そのメッセージに使用できる正確なバイト数が示されます。セグメントを空、.、.. にすることはできません。
/ で終わる 0 バイトのキーはフォルダーマーカーであり、AWS コンソールがフォルダーを作成する方法と同じです。
配信される Content-Type は、REST API と同様に拡張子から決定されます。実行ファイルは InvalidArgument で拒否され、.html、.svg、.xml はダウンロードとして配信されます。

メタデータ、キャッシュ、有効期限

x-amz-meta-* ヘッダーは Pro と Enterprise で保持されます (最大 5 キー、512 バイト。超えると MetadataTooLarge)。その他のプランでは破棄されます。
Cache-Control と Content-Disposition は保持されます。キャッシュしない Cache-Control (no-cache、no-store、max-age=0) は、Enterprise 以外では AccessDenied で拒否されます。
プレフィックスごとのルールは、自動削除を含め、S3 経由で書き込まれたオブジェクトにも適用されます。ルールの max_size と extensions は、REST のアップロードにのみ適用されます。

制限

制限	値
アカウントあたりのリクエスト (10 秒ごと)	Hobby 100 · Standard 200 · Pro 400 · Enterprise 600
サーバー側のコピー (`CopyObject`、`UploadPartCopy`)	10 秒間に 20 件
`DeleteObjects` で削除されるキー	10 秒間に 2000 件
未完了のマルチパートアップロード	アカウントあたり 32 件。REST のチャンクアップロードと共有
単一の `PutObject`	100 MB
パート (`UploadPart`)	5 MB〜80 MB。最後のパートを除く
オブジェクトサイズ	10 GiB
無効な認証情報	失敗が多すぎると、その IP は数分間ブロックされます

制限を超えると、ゲートウェイは SlowDown (HTTP 503) を返し、AWS SDK は自動的にバックオフして再試行します。S3 リクエストはプランの API リクエスト制限にカウントされません。ループで再試行する前に、キーペアを確認してください。無効な認証情報を送信しすぎた IP は数分間ブロックされます。

パートサイズ

マルチパート対応のツールは大きなファイルを自動的に分割します。各パートは 80 MB 以下にしてください。AWS CLI (8 MB) と rclone (5 MB) のデフォルトはすでにこの範囲内です。

aws configure set default.s3.multipart_chunksize 64MB

from boto3.s3.transfer import TransferConfig

config = TransferConfig(multipart_chunksize=64 * 1024 * 1024)
s3.upload_file("backup.tar.gz", "private", "backups/backup.tar.gz", Config=config)

import { Upload } from "@aws-sdk/lib-storage";

await new Upload({
  client: s3,
  params: { Bucket: "private", Key: "backups/backup.tar.gz", Body: stream },
  partSize: 64 * 1024 * 1024, // 最大 80 MB
}).done();

書き込みには有料プランが必要です。有料プランがない場合、および読み取り専用の legacy バケットでは、書き込みは AccessDenied を返します。ストレージ枠は REST API と同様に適用されます。

エラー

ゲートウェイは標準の S3 XML エラーを返すため、SDK はそれらをネイティブに処理します。

エラー	発生する状況
`AccessDenied`	有料プランがない、読み取り専用のキー、`legacy` への書き込み、またはプランに含まれないオプション。
`NoSuchBucket`	バケットが `public`、`private`、`legacy` のいずれでもない。
`NoSuchKey`	オブジェクトが存在しない。
`InvalidArgument`	ブロックされたファイル形式 (実行ファイルとインストーラー) または形式が正しくないヘッダー。
`QuotaExceeded`	アカウントが含まれるストレージの上限に達した。
`EntityTooLarge` / `EntityTooSmall`	100 MB を超える `PutObject`、80 MB を超えるパート、または最後ではない 5 MB 未満のパート。
`InvalidPart` / `InvalidPartOrder` / `NoSuchUpload`	不正なパートによるマルチパートの完了、またはすでに存在しないアップロード。
`BadDigest`	本文が `Content-MD5` または `x-amz-checksum-*` ヘッダーと一致しない。
`PreconditionFailed`	`If-Match` または `If-None-Match` の条件が満たされなかった。
`MetadataTooLarge`	メタデータが 5 キーまたは 512 バイトを超えている。
`KeyTooLongError`	キーが長すぎる (約 1000 バイト)。メッセージにアカウントの正確な上限が示されます。
`SlowDown`	HTTP 503: レート制限または未完了アップロードの上限に達した。SDK は自動的にバックオフを入れて再試行します。
`NotImplemented`	操作がサポートされていない (上記を参照)。

はじめに

オブジェクト

チャンクアップロード

アカウント

共有リンク

S3

認証情報

バケット

設定

サポートされる操作

キー

メタデータ、キャッシュ、有効期限

制限

パートサイズ

エラー

​認証情報

​バケット

​設定

​サポートされる操作

​キー

​メタデータ、キャッシュ、有効期限

​制限

​パートサイズ

​エラー

認証情報

バケット

設定

サポートされる操作

キー

メタデータ、キャッシュ、有効期限

制限

パートサイズ

エラー