Blob Storage の 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

バケット

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

バケット	内容	アクセス
`public`	公開ファイル。`https://blob.squarecloud.dev/pub/<user_id>/<key>` で配信されます	読み取りと書き込み
`private`	公開 URL のないプライベートファイル	読み取りと書き込み

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` は検証なしで受け付けられます。1 つのリクエストに含められる `x-amz-checksum-` の値ヘッダーは 1 つまでです (それ以外は `InvalidRequest`)。署名付きアップロードでは、署名済みの `x-amz-checksum-sha256` または `x-amz-checksum-crc32` で内容を固定できます。`aws-chunked` の本文に対応しています。
互換性	`GetBucketVersioning`、`GetBucketAcl`、`GetObjectAcl` およびタグの読み取りは固定値を返すため、これらを確認するツールも動作し続けます。

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

キー

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

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

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

制限

制限	値
アカウントあたりのリクエスト (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();

書き込みには有効なプランが必要です。有効なプランがない場合、書き込みは AccessDenied を返します。ストレージ枠は REST API と同様に適用され、開いているすべてのマルチパートアップロードのパートの合計が枠の残りに対してカウントされます (QuotaExceeded)。

エラー

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

エラー	発生する状況
`AccessDenied`	有効なプランがない、読み取り専用のキー、またはプランに含まれないオプション。
`NoSuchBucket`	バケットが `public` でも `private` でもない。
`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

Blob Storage の S3 互換性

認証情報

バケット

設定

サポートされる操作

キー

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

制限

パートサイズ

エラー

​認証情報

​バケット

​設定

​サポートされる操作

​キー

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

​制限

​パートサイズ

​エラー

認証情報

バケット

設定

サポートされる操作

キー

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

制限

パートサイズ

エラー