> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Blob Storage API クイックスタート
> Blob Storage API で最初のファイルをアップロードしてダウンロードします。v1 のベース URL、Authorization ヘッダー、curl でのアップロード、レスポンス、ダウンロードリンクを説明します。
Blob Storage はファイルを保存し、公開ファイルを CDN から配信し、プライベートファイルへのリンクを発行します。このページでは、API キーの用意からファイルのアップロード、ダウンロードリンクの取得までを `curl` で説明します。ストレージはすべてのプランに含まれています。プラン、料金、FAQ は [Blob Storage](/ja/services/blob) を参照してください。
## ベース URL
このリファレンスのすべてのエンドポイントは、次の URL からの相対パスです。
```bash theme={"system"}
https://blob.squarecloud.app/v1
```
## 認証
Blob Storage は [Square Cloud API](/ja/api-reference/introduction) と同じ API キーを `Authorization` ヘッダーで受け取ります。アップロードには `blob:write` スコープ、一覧とダウンロードには `blob:read` スコープが必要で、キーを特定のアプリケーションに制限することはできません。[アカウントのセキュリティ設定](https://squarecloud.app/ja/account/security)でキーを作成し、環境変数に保管してください。
```bash theme={"system"}
export SQUARECLOUD_API_KEY="your-api-key"
```
スコープとアップロードトークンの詳細は[認証](/ja/blob-reference/authentication)を参照してください。
## ファイルをアップロードする
[オブジェクトのアップロード](/ja/blob-reference/endpoint/post)は、ファイルを `multipart/form-data` で、拡張子を除いた名前をクエリで受け取ります。
```bash theme={"system"}
curl --request POST \
--url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
--header "Authorization: $SQUARECLOUD_API_KEY" \
--form 'file=@./logo.png'
```
```json theme={"system"}
{
"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` はすぐにブラウザーや `![]()
` タグで使えます。他のすべてのルートが `id` を受け取るので、返された `id` をそのまま保存してください。
1 回のリクエストで扱えるファイルは 512 バイトから 100 MB までです。最大 10 GiB までのより大きなファイルは、[チャンクアップロード](/ja/blob-reference/endpoint/chunked-init)または [S3 ゲートウェイ](/ja/blob-reference/s3-compatibility)を使います。
## プライベートファイルをアップロードする
`private=true` を追加すると、ファイルには公開 URL が付きません (`url` は `null` です)。
```bash theme={"system"}
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` からダウンロードできます。プライベートファイルの場合は、[オブジェクトのダウンロード](/ja/blob-reference/endpoint/download)が認証情報なしで使える一時リンクに署名してリダイレクトするため、`curl -L` でファイルを保存できます。
```bash theme={"system"}
curl -L --output invoice.pdf \
--url 'https://blob.squarecloud.app/v1/objects/download?object=' \
--header "Authorization: $SQUARECLOUD_API_KEY"
```
`` はアップロード時の `id` に置き換えてください。`redirect=false` を追加するとリンクを JSON で受け取れるので、他の人に渡せます。取り消しやパスワード保護ができるリンクが必要な場合は、[共有リンク](/ja/blob-reference/endpoint/shares-create)を作成してください。
## ファイルの一覧と削除
[オブジェクトの一覧](/ja/blob-reference/endpoint/list)は、ファイルをページ単位で返します。
```bash theme={"system"}
curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
--header "Authorization: $SQUARECLOUD_API_KEY"
```
[オブジェクトの削除](/ja/blob-reference/endpoint/delete)は、1 つのファイル、または 1 回のリクエストで最大 100 個のファイルを削除します。
```bash theme={"system"}
curl --request DELETE \
--url 'https://blob.squarecloud.app/v1/objects' \
--header "Authorization: $SQUARECLOUD_API_KEY" \
--header 'Content-Type: application/json' \
--data '{ "object": "" }'
```
## うまくいかないとき
エラーは `{ "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 を超えています。チャンクアップロードを使ってください。 |
すべてのコードは[エラー](/ja/blob-reference/errors)に記載しています。
## 次のステップ
JavaScript からファイルをアップロード、管理できます。チャンクアップロードも自動で処理されます。
aws-cli、boto3、rclone、または任意の AWS SDK を使えます。
一時リンク、共有リンク、それぞれの使い分け。
API キーを公開せずに訪問者がアップロードできるようにします。