Manajemen CRUD File & Folder
Operasi CRUD menyeluruh untuk file dan folder virtual: telusuri hierarki, ubah nama/pindahkan aset dengan sinkronisasi otomatis penyimpanan, timpa file biner in-place, dan lakukan penghapusan atomik.
Mendaftar File & Folder (`listContents`)
Dapatkan seluruh file, folder, dan rekam jejak breadcrumbs pada root proyek maupun di dalam subfolder tertentu:
import { Cloudizero } from "@cloudizero/sdk";
const cz = new Cloudizero({ apiKey: process.env.CLOUDIZERO_API_KEY! });
// Daftar konten root direktori
const rootContents = await cz.storage.listContents({
projectId: "prj_LXAlEW70v24YSc0y",
});
console.log("Root Folders:", rootContents.folders);
console.log("Root Files:", rootContents.files);
// Daftar konten subfolder spesifik berdasarkan folderId
const folderContents = await cz.storage.listContents({
projectId: "prj_LXAlEW70v24YSc0y",
folderId: "fld_ARaZjwdP...",
});
console.log("Current Breadcrumbs:", folderContents.breadcrumbs);Mengambil Metadata Aset (`getFile`)
Ambil metadata relasional dan dapatkan URL unduhan presigned untuk aset privat:
// Mengambil metadata file dan tautan unduhan presigned sementara
const { file, downloadUrl } = await cz.storage.getFile("fil_tsvSl4yY...");
console.log("File Name:", file.name);
console.log("Size:", file.size);
console.log("Direct Download:", downloadUrl);
console.log("Thumbnail URL:", file.thumbnailUrl);Memperbarui & Mengganti File (`updateFile` & `replaceFile`)
Ubah nama file, pindahkan antar folder, atau ganti muatan binernya secara in-place dengan mempertahankan fileId yang sama:
// 1. Pembaruan Metadata (Ubah nama file atau pindahkan ke folder lain)
// Otomatis memindahkan objek terkait di penyimpanan untuk sinkronisasi key & URL CDN
const renamedFile = await cz.storage.updateFile({
fileId: "fil_tsvSl4yY...",
name: "hero-banner-2026.webp",
folderId: "fld_ARaZjwdP...", // atau null / "root" untuk pindah ke root proyek
});
// 2. Penggantian Biner In-Place (Timpa konten file dengan mempertahankan fileId yang sama)
const replacedFile = await cz.storage.replaceFile({
fileId: "fil_tsvSl4yY...",
file: newFileBuffer,
fileName: "hero-banner-v2.webp",
mimeType: "image/webp",
onProgress: ({ percent }) => console.log(`Mengganti: ${percent}%`),
});Parameter (`UpdateFileOptions`)
| Property | Type | Default | Description |
|---|---|---|---|
| fileId*required | string | — | ID file target yang akan diperbarui (Prefixed ID mis. 'fil_...'). |
| name | string | — | Nama file baru. Otomatis memindahkan jalur key objek penyimpanan. |
| folderId | string | null | — | ID folder target (mis. 'fld_...' atau null / 'root'). Otomatis memindahkan objek penyimpanan. |
| isTrash | boolean | — | Flag status tempat sampah / soft-delete. |
| file | File | Blob | Buffer | Uint8Array | — | Muatan biner baru opsional untuk menimpa konten file di penyimpanan. |
| mimeType | string | — | Tipe MIME yang diperbarui saat menimpa file biner. |
| onProgress | ({ loaded, total, percent }) => void | — | Callback progres unggah saat mengganti muatan biner. |
Unggah Langsung Klien via Presigned URL (`createPresignedUpload` & `completeUpload`)
Hasilkan URL unggah presigned berdurasi terbatas agar browser atau aplikasi mobile klien dapat mengunggah aset biner langsung ke Cloudizero Storage Engine tanpa membebani egress atau memori server Anda:
// 1. Backend: Buat tiket unggah presigned berdurasi terbatas
const ticket = await cz.storage.createPresignedUpload({
projectId: "prj_LXAlEW70v24YSc0y",
fileName: "podcast-episode.mp3",
fileSize: 1024 * 1024 * 45, // 45 MB
mimeType: "audio/mpeg",
});
// Kembalikan 'ticket' ke frontend:
// { uploadUrl, fileId, storageKey, finalFileName }
// 2. Browser / Client: Unggah biner langsung ke Cloudizero Storage Engine via PUT
// await fetch(ticket.uploadUrl, { method: "PUT", body: audioFile, headers: { "Content-Type": audioFile.type } });
// 3. Backend: Rekam metadata dan finalisasi aset di katalog Cloudizero
const file = await cz.storage.completeUpload({
fileId: ticket.fileId,
projectId: "prj_LXAlEW70v24YSc0y",
fileName: ticket.finalFileName,
mimeType: "audio/mpeg",
fileSize: 1024 * 1024 * 45,
storageKey: ticket.storageKey,
});CRUD Folder Virtual (`createFolder`, `updateFolder`, `deleteFolder`)
Buat, periksa, ubah nama, pindahkan, dan hapus folder virtual secara rekursif via SDK:
// 1. Buat folder virtual
const folder = await cz.storage.createFolder({
projectId: "prj_LXAlEW70v24YSc0y",
name: "Marketing Assets",
parentId: null, // opsional: parent folder ID untuk folder bersarang
});
// 2. Ambil informasi folder atau daftar folder
const folderInfo = await cz.storage.getFolder(folder.id);
const rootFolders = await cz.storage.listFolders({
projectId: "prj_LXAlEW70v24YSc0y",
parentId: "root",
});
// 3. Ubah nama atau pindahkan folder (otomatis sinkronisasi subfolder dan storage key)
const updatedFolder = await cz.storage.updateFolder({
folderId: folder.id,
name: "Brand & Marketing",
parentId: null,
});
// 4. Hapus folder (menghapus subfolder dan objek penyimpanan secara rekursif)
const deleted = await cz.storage.deleteFolder(folder.id);
console.log(`Dihapus ${deleted.deletedFoldersCount} folder dan ${deleted.deletedFilesCount} file`);Metode Folder SDK
| Property | Type | Default | Description |
|---|---|---|---|
| createFolder(options)*required | CreateFolderOptions => Promise<StorageFolder> | — | Membuat folder di proyek ({ projectId, name, parentId?, path? }). |
| getFolder(folderId)*required | string => Promise<StorageFolder> | — | Mengambil rekaman folder tunggal berdasarkan ID-nya (mis. 'fld_...'). |
| listFolders(options)*required | ListFoldersOptions => Promise<StorageFolder[]> | — | Mendaftar folder di dalam direktori proyek ({ projectId, parentId? }). |
| updateFolder(options)*required | UpdateFolderOptions => Promise<StorageFolder> | — | Mengubah nama atau memindahkan folder ({ folderId, name?, parentId? }) dan cascade storage key. |
| deleteFolder(folderId)*required | string => Promise<DeleteFolderResult> | — | Menghapus folder secara rekursif beserta subfolder dan seluruh objek penyimpanan di dalamnya. |
Intelijen Dokumen & Ekstraksi Halaman PDF (`getFilePages` & `extractPdfPages`)
Akses hasil ekstraksi halaman resolusi tinggi, thumbnail, dan daftar bab dari dokumen multi-halaman (seperti PDF), atau picu proses ekstraksi secara terprogram:
// 1. Dapatkan daftar halaman, dimensi, URL CDN, dan bab dokumen PDF
const doc = await cz.storage.getFilePages("fil_tsvSl4yYKEOlO4KN");
console.log(`Total Halaman: ${doc.pageCount}`);
console.log("Status Pemrosesan:", doc.processingStatus);
console.log("Thumbnail Dokumen:", doc.thumbnailUrl);
console.log("Halaman Pertama:", doc.pages[0]?.url);
console.log("Daftar Bab:", doc.chapters);
// 2. Memicu antrean ekstraksi halaman PDF (asinkron)
const job = await cz.storage.extractPdfPages("fil_tsvSl4yYKEOlO4KN");
console.log("Status Antrean:", job.message);Pencarian Multimodal Hibrida (`search`)
Pencarian berbasis bahasa alami yang memadukan vektor semantik (768 dimensi) dengan pencocokan kata kunci eksak di seluruh aset proyek:
// Pencarian multimodal hibrida (vektor semantik + kata kunci)
const searchResults = await cz.storage.search({
projectId: "prj_LXAlEW70v24YSc0y",
query: "sunset over the beach with palm trees",
});
console.log(`Mode Pencarian: ${searchResults.mode} (${searchResults.totalCount} hasil)`);
searchResults.results.forEach((match) => {
console.log(`- ${match.name} [Skor: ${match.similarityScore}, Tipe: ${match.matchType}]`);
console.log(` CDN URL: ${match.url}`);
});AI Visual Describe & Teks Alt WCAG (`describeImage`)
Gunakan AI vision multimodal untuk menganalisis aset gambar secara otomatis, menghasilkan teks alt aksesibilitas WCAG, tag SEO, deskripsi visual, dan palet warna:
// Analisis visual AI untuk teks alt WCAG, tag SEO, dan palet warna
const aiResult = await cz.storage.describeImage("fil_tsvSl4yYKEOlO4KN", {
locale: "id", // atau "en" untuk bahasa Inggris
force: false,
});
console.log("Teks Alt WCAG:", aiResult.altText);
console.log("Tag SEO:", aiResult.aiMetadata.tags);
console.log("Deskripsi Visual:", aiResult.aiMetadata.description);
console.log("Palet Warna Dominan:", aiResult.aiMetadata.dominantColors);Transformasi Gambar CDN Dinamis di Edge (`getCdnUrl`)
Hasilkan URL CDN publik yang bersih dan otoritatif dengan manipulasi gambar on-the-fly di jaringan edge global Cloudizero:
// 1. Dapatkan URL CDN asli untuk aset penyimpanan
const originalUrl = cz.storage.getCdnUrl("usr_IIZHBI7BIsUY7IOL/prj_LXAlEW70v24YSc0y/banner.png");
console.log("Original CDN URL:", originalUrl);
// => https://cdn.cloudizero.com/usr_IIZHBI7BIsUY7IOL/prj_LXAlEW70v24YSc0y/banner.png
// 2. Transformasi gambar dinamis di edge (lebar, tinggi, kualitas, format WebP)
const optimizedThumb = cz.storage.getCdnUrl("usr_IIZHBI7BIsUY7IOL/prj_LXAlEW70v24YSc0y/banner.png", {
width: 400,
height: 300,
quality: 80,
format: "webp",
fit: "cover",
});
console.log("Optimized Thumbnail URL:", optimizedThumb);
// => https://cdn.cloudizero.com/usr_IIZHBI7BIsUY7IOL/prj_LXAlEW70v24YSc0y/banner.png?w=400&h=300&q=80&format=webp&fit=coverProfil Akun & Pemantauan Kuota Waktu-Nyata (`cz.getProfile`)
Pantau tier paket langganan, sisa kapasitas penyimpanan, dan batas limit akun secara terprogram:
// Periksa profil akun, tier paket langganan, dan pemakaian kuota waktu-nyata
const profile = await cz.getProfile();
console.log(`Paket Langganan: ${profile.plan} (${profile.isTrial ? "Trial Aktif" : "Reguler"})`);
console.log(`Kapasitas Terpakai: ${profile.stats.totalStorageBytes} / ${profile.limits.storageBytes} byte (${profile.stats.storagePercent}%)`);
console.log(`Sisa Penyimpanan: ${profile.stats.remainingStorageBytes} byte`);
console.log(`Total Proyek: ${profile.stats.projectsCount} / ${profile.limits.maxProjects}`);
console.log(`Total File: ${profile.stats.filesCount}`);Manajemen Siklus Hidup Proyek (`projects`)
Kelola boundary proyek Anda langsung melalui SDK: mendaftar, membuat, memperbarui, dan menghapus proyek.
// 1. Ambil daftar seluruh proyek yang dapat diakses
const projects = await cz.projects.list();
// 2. Buat proyek baru (memerlukan API key dengan Akses Global)
const newProject = await cz.projects.create({
name: "Mobile App Assets",
description: "Asset bucket untuk flutter mobile app",
});
// 3. Perbarui nama atau deskripsi proyek
const updated = await cz.projects.update(newProject.id, {
name: "Mobile App Production Assets",
});
// 4. Perbarui urutan tampilan proyek
await cz.projects.reorder([newProject.id, "prj_LXAlEW70v24YSc0y"]);
// 5. Hapus proyek secara permanen beserta seluruh file dan foldernya
const res = await cz.projects.delete(newProject.id);
console.log(res.message);Menghapus Aset Permanen (`deleteFile`)
Penghapusan aset bersifat atomik: Cloudizero secara simultan membersihkan objek biner dari penyimpanan dan menghapus rekamannya dari basis data.
// Hapus file secara permanen dari penyimpanan dan database
const res = await cz.storage.deleteFile("fil_tsvSl4yYKEOlO4KN");
if (res.success) {
console.log("Aset berhasil dihapus:", res.message);
}