Blob Storage API クイックスタート

Blob Storage はファイルを保存し、公開ファイルを CDN から配信し、プライベートファイルへのリンクを発行します。このページでは、API キーの用意からファイルのアップロード、ダウンロードリンクの取得までを curl で説明します。ストレージはすべてのプランに含まれています。プラン、料金、FAQ は Blob Storage を参照してください。

ベース URL

このリファレンスのすべてのエンドポイントは、次の URL からの相対パスです。

https://blob.squarecloud.app/v1

認証

Blob Storage は Square Cloud API と同じ API キーを Authorization ヘッダーで受け取ります。アップロードには blob:write スコープ、一覧とダウンロードには blob:read スコープが必要で、キーを特定のアプリケーションに制限することはできません。アカウントのセキュリティ設定でキーを作成し、環境変数に保管してください。

export SQUARECLOUD_API_KEY="your-api-key"

スコープとアップロードトークンの詳細は認証を参照してください。

ファイルをアップロードする

オブジェクトのアップロードは、ファイルを multipart/form-data で、拡張子を除いた名前をクエリで受け取ります。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./logo.png'

{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/images/logo.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png",
    "size": 416230,
    "name": "logo",
    "prefix": "images",
    "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "replaced": false
  }
}

ファイルはデフォルトで公開されるため、url はすぐにブラウザーや <img> タグで使えます。他のすべてのルートが id を受け取るので、返された id をそのまま保存してください。 1 回のリクエストで扱えるファイルは 512 バイトから 100 MB までです。最大 10 GiB までのより大きなファイルは、チャンクアップロードまたは S3 ゲートウェイを使います。

プライベートファイルをアップロードする

private=true を追加すると、ファイルには公開 URL が付きません (url は null です)。

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./invoice.pdf'

ファイルをダウンロードする

公開ファイルは url からダウンロードできます。プライベートファイルの場合は、オブジェクトのダウンロードが認証情報なしで使える一時リンクに署名してリダイレクトするため、curl -L でファイルを保存できます。

curl -L --output invoice.pdf \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=<id>' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

<id> はアップロード時の id に置き換えてください。redirect=false を追加するとリンクを JSON で受け取れるので、他の人に渡せます。取り消しやパスワード保護ができるリンクが必要な場合は、共有リンクを作成してください。

ファイルの一覧と削除

オブジェクトの一覧は、ファイルをページ単位で返します。

curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

オブジェクトの削除は、1 つのファイル、または 1 回のリクエストで最大 100 個のファイルを削除します。

curl --request DELETE \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "object": "<id>" }'

うまくいかないとき

エラーは { "status": "error", "code": "..." } の形式で返されます。最初に遭遇しやすいのは次のコードです。

コード	HTTP	対処
`ACCESS_DENIED`	401	キーがないか認識されていません。`Authorization` ヘッダーを確認してください。
`PERMISSION_DENIED`	401	アカウントに有効なプランがないため、アップロードできません。
`MISSING_SCOPE`	403	キーに `blob:write` または `blob:read` がありません。そのスコープを持つキーを作成してください。
`RESOURCE_NOT_ALLOWED`	403	キーがアプリケーションに制限されています。その制限のないキーを使ってください。
`FILE_TOO_LARGE`	413	ファイルが 100 MB を超えています。チャンクアップロードを使ってください。

すべてのコードはエラーに記載しています。

次のステップ

Blob SDK

JavaScript からファイルをアップロード、管理できます。チャンクアップロードも自動で処理されます。

S3 互換性

aws-cli、boto3、rclone、または任意の AWS SDK を使えます。

リンクと共有

一時リンク、共有リンク、それぞれの使い分け。

ブラウザーからのアップロード

API キーを公開せずに訪問者がアップロードできるようにします。

​ベース URL

​認証

​ファイルをアップロードする

​プライベートファイルをアップロードする

​ファイルをダウンロードする

​ファイルの一覧と削除

​うまくいかないとき

​次のステップ