オブジェクト

オブジェクト ID は不透明です (pub/...、prv/...)。返されたとおりに保存し、組み立てたりパースしたりせず、update() が新しい ID を返したら保存している ID を置き換えてください。オブジェクト ID を参照してください。

一覧

list() は、カーソルをたどってすべてのページを取得する非同期ジェネレーターです。順序は保証されません。

for await (const object of blob.list({ prefix: "avatars/" })) {
    console.log(object.id, object.size, object.url);
}

listPage() は 1 ページを取得します。手動でページ送りをする場合や、folders を取得する場合に使います:

const { objects, folders, continuationToken } = await blob.listPage({
    prefix: "avatars/",
    delimiter: "/",
});

// next page
if (continuationToken) {
    const next = await blob.listPage({ prefix: "avatars/", delimiter: "/", cursor: continuationToken });
}

オプション	型	説明
`prefix`	`string`	このプレフィックス配下のオブジェクトのみ。
`delimiter`	`"/"`	フォルダーごとにグループ化します。ページは `folders` も返します。
`private`	`boolean`	プライベート (`true`) または公開 (`false`) のオブジェクトのみ。
`limit`	`number`	1 ページあたりのオブジェクト数。1〜1000 (デフォルト 1000)。
`cursor`	`string`	`listPage()` のみ: 前のページの `continuationToken`。

ページには objects、folders (delimiter を指定した場合のみ)、continuationToken (最後のページには存在しません) があります。一覧の各オブジェクトには id、size、created_at、expires_at、private、url、etag があります。Blob オブジェクトの一覧を参照してください。

オブジェクトの詳細

const info = await blob.info(id);

id、size、content_type、etag、created_at、expires_at、private、url、cache_control、content_disposition、original_name、metadata、legacy を返します。Blob オブジェクト情報を参照してください。

created_at はストレージ上の最終更新日時です。オブジェクトをコピーする更新 (公開範囲、有効期限、ヘッダー) を行うとリセットされます。

ダウンロードリンク

const { url, expires_at } = await blob.downloadUrl(id, { expires: 3600 });

公開オブジェクトには、expires_at: null の恒久的な CDN URL が返されます。
プライベートオブジェクト、または disposition か filename を指定した呼び出しには、expires 秒間 (最大 24 時間) 有効な一時リンクが返されます。

一時リンクは取り消せません。取り消し可能なリンク、パスワード保護されたリンク、ダウンロード回数を制限したリンクには、共有を使ってください。

オプション	型	説明
`expires`	`number`	リンクの有効期間 (秒)。60〜86400 (デフォルト 3600)。
`disposition`	`"inline"` \| `"attachment"`	このリンクの `Content-Disposition` を上書きします。
`filename`	`string`	ブラウザがダウンロードを保存するときのファイル名。

結果には url、expires_at、private、size、content_type があります。Blob オブジェクトのダウンロードを参照してください。

オブジェクトの更新

update() は、1 つ、または最大 50 個のオブジェクトの公開範囲、有効期限、キャッシュ、disposition、メタデータを変更します。常に配列を返し、オブジェクトごとに 1 つの結果が含まれ、各結果は自身の成否を ok で報告します。

const [result] = await blob.update(id, { private: true, expire: null });

if (result.ok) {
    id = result.id; // the id changed: store the new one
} else {
    console.error(result.code);
}

変更	型	説明
`private`	`boolean`	オブジェクトをプライベートまたは公開にします。ID が変わります。
`expire`	`string \| null`	新しい有効期限。`null` で削除します。ID が変わります。
`cache_control`	`string \| null`	`null` で削除します。
`disposition`	`"inline"` \| `"attachment"` \| `null`	`null` で削除します。
`metadata`	`Record<string, string \| null> \| null`	`{ key: null }` で 1 つのキーを削除し、`null` ですべて削除します。

成功した結果 (ok: true) には、object (送信した ID)、changed、id (変更後の ID)、private、url、expires_at、size があります。失敗した結果 (ok: false) には object と code があります。バッチは、オブジェクトごとの失敗では例外をスローしません。Blob オブジェクトの更新を参照してください。

削除

削除は即時かつ恒久的です。ゴミ箱はありません。

// Single id: resolves to nothing, throws OBJECT_NOT_FOUND when missing
await blob.delete(id);

// Batch, up to 100 ids
const { deleted, not_found, failed } = await blob.delete([id1, id2]);

呼び出し	戻り値	オブジェクトが存在しない場合
`delete(id)`	`void`	`SquareCloudBlobError` (`OBJECT_NOT_FOUND`) をスローします。
`delete([ids])`	`{ deleted, not_found, failed }`	`not_found` で報告されます。`failed` には `{ id, code }` が列挙されます。

配列に ID が 1 つだけの場合も、SDK は { deleted, not_found, failed } を返します。存在しないオブジェクトは not_found に入り、DELETE_FAILED や PREFIX_NOT_ALLOWED は例外をスローする代わりに failed に入ります。その他のエラー (認証、レート制限、ネットワーク) は引き続きスローされます。Blob オブジェクトの削除を参照してください。

コピー、移動、名前変更

どちらもファイルをダウンロードせずに、サーバー上で実行されます。

// Copy: counts toward your storage quota
await blob.copy(id, { name: "photo_copy", prefix: "backup" });

// Move or rename: does not count toward the quota
const moved = await blob.move(id, { name: "renamed" });
id = moved.id;

move(source, destination, options) は、move: true を指定した copy() です。

コピー先のフィールド	型	説明
`name`	`string`	必須。拡張子を除いた名前。コピー先はコピー元の拡張子を引き継ぎます。
`prefix`	`string`	コピー先のプレフィックス。
`private`	`boolean`	コピー先の公開範囲。
`security_hash`	`boolean`	名前に `_<hash>` を付加します。
`expire`	`string \| null`	省略するとコピー元の有効期限を維持し、`null` で削除します。

オプション	受け付けるメソッド	説明
`overwrite`	`copy()`, `move()`	`true` にすると、コピー先の既存オブジェクトを置き換えます。
`move`	`copy()`	`true` にすると、コピーが成功した時点でコピー元を削除します (`move()` の呼び出しと同じ)。

結果には id、private、url、expires_at、size、source、moved、replaced があります。Blob オブジェクトのコピーを参照してください。

update()、delete()、copy()、move() は書き込みです。1 回のみ試行され、リトライされることはありません。リトライポリシーを参照してください。

サービス

Runtimes

プラットフォーム

トラブルシューティング

CLI

SDKs

Changelog

一覧

オブジェクトの詳細

ダウンロードリンク

オブジェクトの更新

削除

コピー、移動、名前変更

​一覧

​オブジェクトの詳細

​ダウンロードリンク

​オブジェクトの更新

​削除

​コピー、移動、名前変更

一覧

オブジェクトの詳細

ダウンロードリンク

オブジェクトの更新

削除

コピー、移動、名前変更