Dosyalar
Dosya yükleme
Basit yükleme, büyük dosyalar için parçalı yükleme, tekrar deneme ve Idempotency-Key.
İki yol var:
| Basit yükleme | Parçalı yükleme | |
|---|---|---|
| Uç | POST /files | POST /uploads → depolamaya PUT → POST /uploads/{id}/complete |
| Boyut | En fazla 50 MB | Planındaki tek dosya sınırına kadar |
| İstek sayısı | 1 | En az 3 |
| Dosya nereden geçer | Drive sunucusu | Doğrudan depolama (storage.kivilio.com) |
Basit yükleme
Gövde dosyanın kendisi; ad ve hedef klasör sorgu dizesinde:
# rapor.txt dosyasını Drive'ım köküne yükler (en fazla 50 MB).
curl -sS -X POST "https://drive.kivilio.com/api/v1/files?name=rapor.txt" \
-H "Authorization: Bearer $KIVILIO_API_KEY" \
-H "Content-Type: text/plain" \
--data-binary @rapor.txt| Sorgu | |
|---|---|
name | Dosya adı (zorunlu) |
parentId | Hedef klasör. Yoksa Drive'ım kökü (klasörle sınırlı anahtarda anahtarın klasörü) |
checksum | İsteğe bağlı SHA-256 (onaltılık), bilgi olarak saklanır |
Content-Type dosyanın türüdür, Content-Length zorunludur. multipart/form-data da kabul edilir: file alanı (zorunlu), name ve parentId alanları.
Parçalı yükleme
- Başlat:
POST /uploadsgövdesi{ name, sizeBytes, mimeType, parentId }. Drive adı, kotayı ve hedefi denetler, dosya için yer ayırır. - Gönder: yanıt
mode: "single"ise tek bir imzalıPUTadresi (headersaynen gönderilir);mode: "multipart"ise parça adresleri (partSizebayt). İlk 100 parçanın adresi yanıtta, kalanlar ve süresi dolanlarPOST /uploads/{id}/partsile alınır. - Tamamla:
POST /uploads/{id}/complete. Drive boyutu doğrular; dosyaREADYolur.
import { open, stat } from "node:fs/promises";
const BASE = "https://drive.kivilio.com";
const auth = { Authorization: `Bearer ${process.env.KIVILIO_API_KEY}` };
const path = "video.mp4";
const size = (await stat(path)).size;
async function api(method, url, body) {
const res = await fetch(`${BASE}/api/v1${url}`, {
method,
headers: { ...auth, "Content-Type": "application/json" },
body: body && JSON.stringify(body),
});
if (!res.ok) throw new Error(`${method} ${url}: HTTP ${res.status} ${await res.text()}`);
return res.json();
}
// 1. Başlat: Drive ad, boyut ve kotayı denetler, imzalı yükleme adresleri verir.
const ticket = await api("POST", "/uploads", {
name: "video.mp4",
sizeBytes: size,
mimeType: "video/mp4",
});
// 2. Dosyayı doğrudan depolamaya gönder (Drive'dan geçmez). Authorization başlığı GÖNDERİLMEZ.
const file = await open(path);
try {
if (ticket.mode === "single") {
const body = await file.readFile();
const put = await fetch(ticket.url, { method: "PUT", headers: ticket.headers, body });
if (!put.ok) throw new Error(`PUT: HTTP ${put.status}`);
} else {
// İlk 100 parçanın adresi bilette; fazlası için POST /uploads/{id}/parts.
for (const part of ticket.parts) {
const start = (part.partNumber - 1) * ticket.partSize;
const length = Math.min(ticket.partSize, size - start);
const buf = Buffer.alloc(length);
await file.read(buf, 0, length, start);
const put = await fetch(part.url, { method: "PUT", body: buf });
if (!put.ok) throw new Error(`Parça ${part.partNumber}: HTTP ${put.status}`);
}
}
} finally {
await file.close();
}
// 3. Tamamla: Drive boyutu doğrular, dosya hazır olur.
const node = await api("POST", `/uploads/${ticket.uploadId}/complete`);
console.log("Hazır:", node.id, node.status);Vazgeçersen DELETE /uploads/{id} ayrılan yeri hemen bırakır; yarım kalan yüklemeler 24 saat sonra kendiliğinden temizlenir.
Ad çakışması
Aynı klasörde aynı adda bir öğe varsa yanıt 409 name_conflict olur ve suggestion alanında boş bir ad önerilir (ör. rapor (1).pdf). Önerilen adla tekrar gönderebilirsin.
Tekrar deneme ve Idempotency-Key
Ağ kesildiğinde isteğin sunucuya ulaşıp ulaşmadığını bilemezsin. Yazma isteklerine bir Idempotency-Key ekle; aynı anahtarla 24 saat içinde gönderilen aynı istek ikinci kez işlenmez, ilk başarılı yanıt aynen döner (Idempotent-Replayed: true başlığıyla):
import { randomUUID } from "node:crypto";
const BASE = "https://drive.kivilio.com";
// Her mantıksal işlem için bir anahtar üret; tekrar denemelerde AYNISINI gönder.
const key = randomUUID();
function upload() {
return fetch(`${BASE}/api/v1/files?name=fatura-2026-11.pdf`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KIVILIO_API_KEY}`,
"Content-Type": "application/pdf",
"Idempotency-Key": key,
},
body: new TextEncoder().encode("%PDF-1.7 örnek"),
});
}
const first = await upload();
// Ağ koptu sanıp yeniden denesen bile ikinci dosya oluşmaz:
const retry = await upload();
const a = await first.json();
const b = await retry.json();
console.log(a.id === b.id, retry.headers.get("Idempotent-Replayed")); // true "true"- Anahtar 1–200 karakter, boşluksuz (UUID önerilir). Kapsamı senin anahtarın; başka kullanıcılarınkiyle karışmaz.
- Aynı anahtarı farklı bir istekle kullanırsan
422 idempotency_mismatch. - İlk istek hâlâ sürüyorsa
409 conflict; biraz bekleyip tekrar dene. - Hata alan istekler saklanmaz: aynı anahtarla düzeltip yeniden gönderebilirsin.
Desteklenen uçlar: POST /files, POST /folders, POST /uploads, POST /uploads/{id}/complete, PATCH ve DELETE /nodes/{id}, POST /nodes/{id}/restore, paylaşım uçları, DELETE /trash. Düz bir sır döndüren uçlar (POST /keys, POST /nodes/{id}/link) desteklemez.
Uygulama klasörleri
"Voice kayıtları" gibi klasörlere yükleme yapılamaz (Uygulama klasörleri).