İçeriğe geç

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üklemeParçalı yükleme
UçPOST /filesPOST /uploads → depolamaya PUT → POST /uploads/{id}/complete
BoyutEn fazla 50 MBPlanındaki tek dosya sınırına kadar
İstek sayısı1En az 3
Dosya nereden geçerDrive sunucusuDoğ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
nameDosya adı (zorunlu)
parentIdHedef 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

  1. Başlat: POST /uploads gövdesi { name, sizeBytes, mimeType, parentId }. Drive adı, kotayı ve hedefi denetler, dosya için yer ayırır.
  2. Gönder: yanıt mode: "single" ise tek bir imzalı PUT adresi (headers aynen gönderilir); mode: "multipart" ise parça adresleri (partSize bayt). İlk 100 parçanın adresi yanıtta, kalanlar ve süresi dolanlar POST /uploads/{id}/parts ile alınır.
  3. Tamamla: POST /uploads/{id}/complete. Drive boyutu doğrular; dosya READY olur.
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).