ファイルストレージ
storage カテゴリの 8 件の API 操作を扱います。
| メソッド | パス | 説明 |
|---|---|---|
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/storage | オブジェクトストレージのステータス（runlot storage usage） |
| POST | /v1/orgs/{orgSlug}/projects/{projectName}/storage | オフにしたストレージを再びオンにします |
| DELETE | /v1/orgs/{orgSlug}/projects/{projectName}/storage | プロジェクトのStorageを削除します（runlot storage delete） |
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/storage/public | 公開されているキープレフィックスです(runlot storage public list) |
| POST | /v1/orgs/{orgSlug}/projects/{projectName}/storage/public | キープレフィックスを公開します(runlot storage public add) |
| DELETE | /v1/orgs/{orgSlug}/projects/{projectName}/storage/public | キープレフィックスの公開を解除します(runlot storage public rm) |
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/storage/objects | オブジェクトの一覧表示（runlot storage ls） |
| GET | /v1/orgs/{orgSlug}/projects/{projectName}/storage/objects/{key} | 1 つのオブジェクトに対する有効期間の短い署名付き URL（runlot storage download） |
GET /v1/orgs/{orgSlug}/projects/{projectName}/storage
オブジェクトストレージが有効かどうか、およびそのプレフィックス・クォータ・使用量です。usedBytes は最後に報告された値であるため、レポート間隔の分だけ遅延します — その間にクォータをわずかに超過することがあります。
オブジェクトの一覧取得や署名付き URL はこの API には含まれません。worker から env.storage を使用してください。
viewer 以上が必要です。
operationId getStorage
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | ストレージのステータス | StorageStatus |
| 403 | — | — |
| 404 | — | — |
| 503 | no_core — サービスが一時的に利用できません | Error |
POST /v1/orgs/{orgSlug}/projects/{projectName}/storage
これは冪等です — 2 回呼び出してもプレフィックスは変わらないため、リトライによってオブジェクトが見えなくなることはありません。
リクエストボディはありません。プレフィックスはプロジェクトごとに固定されており、クォータはプランによって設定されるため、どちらも自分で設定できる値ではありません。
有効化すると、env.storage はまもなく worker に接続されます。env.db と同様、再デプロイは不要です。
member 以上が必要です。storage.grant として監査されます。
operationId grantStorage
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 付与ステータス(既に存在していた場合は既存の値) | StorageStatus |
| 403 | — | — |
| 404 | — | — |
| 503 | no_core — サービスが一時的に利用できません | Error |
DELETE /v1/orgs/{orgSlug}/projects/{projectName}/storage
オブジェクトは削除されません。 ストレージをオフにするとプロジェクトから切り離され、監査ログに記録されますが、保存済みのオブジェクトはそのまま残ります。
無効化も冪等です。ストレージが有効化されていなかった場合でも 204 を返します。
admin 以上が必要です — 課金は停止しますが、オブジェクトはそのまま残ります。storage.revoke として監査されます。
operationId revokeStorage
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 204 | 切断済み | — |
| 403 | — | — |
| 404 | — | — |
| 503 | no_core — サービスが一時的に利用できません | Error |
GET /v1/orgs/{orgSlug}/projects/{projectName}/storage/public
このプロジェクトが https://objects.runlot.io/<org>/<project>/<key> で署名なしで配信するキーのプレフィックスです。
保存されるプレフィックスは正規化されます。assets は assets/ になり、/ は空文字列になります。これはプロジェクトのストレージ内のすべてのキーを意味します。マッチングは単純な文字列プレフィックステストであるため、末尾のスラッシュがあることで assets が assets-private/ まで開放してしまうのを防いでいます。
viewer 以上が必要です。
operationId listStoragePublic
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 一覧 | StoragePublicList |
| 403 | — | — |
| 404 | — | — |
| 503 | no_core — サービスが一時的に利用できません | Error |
POST /v1/orgs/{orgSlug}/projects/{projectName}/storage/public
このプレフィックス配下のすべてのキーを、署名なしで誰でも HTTPS 経由で読み取れるようにします。バケット自体は非公開のままで、オブジェクトが読み取られる前にすべてのリクエストがこの一覧と照合されます。
冪等であり、変更後の一覧全体を返します。
プロジェクトあたり最大 20 個のプレフィックスです。
admin 以上が必要です。 公開するとプロジェクトのバイト列がインターネットから読み取り可能になります。storage.public.add として監査され、正規化によって送信内容と保存内容が異なる場合があるため、両方が記録されます。
operationId addStoragePublic
リクエストボディ: application/json · StoragePublicRequest
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 変更後の一覧 | StoragePublicList |
| 400 | プレフィックスが空である、正規化できない、またはプロジェクトの範囲を超えてしまう場合 | Error |
| 403 | — | — |
| 404 | — | — |
| 409 | storage_not_granted、または too_many_public_prefixes | Error |
| 503 | no_core — サービスが一時的に利用できません | Error |
DELETE /v1/orgs/{orgSlug}/projects/{projectName}/storage/public
プレフィックスにはスラッシュが含まれる可能性があるため、パスではなくリクエストボディで渡されます。
冪等です — 存在しないものを削除しようとした場合も 200 が返り、一覧は変わりません。
世界中からのアクセスは最大 60 秒間読み取り可能なままです。 公開された一覧はこの TTL でキャッシュされるため、この呼び出しは戻った瞬間に反映される失効処理ではありません。
admin 以上が必要です。storage.public.remove として監査されます。
operationId removeStoragePublic
リクエストボディ: application/json · StoragePublicRequest
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 変更後の一覧 | StoragePublicList |
| 400 | プレフィックスが空、または正規化できない場合 | Error |
| 403 | — | — |
| 404 | — | — |
| 503 | no_core — サービスが一時的に利用できません | Error |
GET /v1/orgs/{orgSlug}/projects/{projectName}/storage/objects
プロジェクトのオブジェクトを 1 ページ分返します。ファイルブラウザと同じように、/ でグループ化されます。entries は prefix の直下にあるオブジェクト、prefixes は 1 階層下のディレクトリです。
キーは worker が書き込むもの（env.storage.put(key, …)）で、内部の p/<projectId>/ プレフィックスは含まれません。このプレフィックスは分離のための境界であり、アドレスの一部ではありません。
キーがこのプロジェクトの公開済みプレフィックス（…/storage/public）の配下にある場合、public は true になり、url は誰でも読める署名なしのアドレスになります。非公開オブジェクトには url が含まれません。このフィールドは「誰でも読める」ことを意味するため、署名付き URL を入れると非公開オブジェクトが公開されているように見えてしまいます。非公開オブジェクトについては …/storage/objects/{key} に問い合わせてください。
ページングは cursor で行い、境界はグループの間に置かれます。そのため、同じディレクトリが 2 回表示されたり、抜け落ちたりすることはありません。cursor はそのまま渡し直してください。含まれない場合は最後のページです。
viewer 以上が必要です。
operationId listStorageObjects
| パラメーター | 場所 | 必須 | 型 | 説明 |
|---|---|---|---|---|
prefix | query | 不可 | string | 一覧表示するキーのプレフィックスです。公開済みプレフィックスと同じ方法で正規化されます。assets は assets/ になり、空の場合はプロジェクトのルートを指します。 |
cursor | query | 不可 | string | 前のページの cursor |
limit | query | 不可 | integer | 1 ページ分の entries と prefixes |
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 1ページ | StorageObjectPage |
| 400 | prefix を正規化できないか、limit が範囲外です | Error |
| 403 | — | — |
| 404 | — | — |
| 409 | storage_not_granted — このプロジェクトにはファイルストレージがありません | Error |
| 502 | objects_unreachable — オブジェクトストアが応答しませんでした | Error |
| 503 | objects_unavailable — この環境にはオブジェクトストアがありません。または no_core | Error |
GET /v1/orgs/{orgSlug}/projects/{projectName}/storage/objects/{key}
5 分間有効な GET URL です。ブラウザまたは CLI がオブジェクトフロントから直接取得します。バイト列はこの API を経由しません。
署名する前にオブジェクトを検索するため、何も入っていないキーはここで 404 になります。数分後に、原因をたどれない別の場所で 404 になる URL が返されることはありません。
署名されるのは GET のみです。アップロードと削除はこの画面にはありません。worker から env.storage を通じて書き込んでください。
viewer 以上が必要です。
operationId signStorageObject
| ステータスコード | 説明 | レスポンスボディ |
|---|---|---|
| 200 | 署名付き URL とオブジェクトのメタデータ | StorageObjectSigned |
| 400 | キーが空か、プロジェクトのプレフィックスの外に出ているか、1024 バイトを超えています | Error |
| 403 | — | — |
| 404 | — | — |
| 409 | storage_not_granted — このプロジェクトにはファイルストレージがありません | Error |
| 503 | objects_unavailable — この環境にはオブジェクトストアがありません。または no_core | Error |