İçeriğe geç
Sursa Developers

POST/v1/uploads/{upload_id}/complete

Yüklemeyi tamamlama

complete_upload

Tüm parçalar alındığında Sursa dosyayı birleştirir, dosyanın tamamının SHA-256 özetini gövdedeki sha256 ile karşılaştırır ve tek istekle yüklemedeki denetimlerin aynısını çalıştırır: içerik imzasına göre biçim ve virüs taraması. Sonuç ready ya da reject_reason ile birlikte rejected olur (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Biçim ya da virüs denetiminin her reddi denetim kaydına file.rejected olarak yazılır.

200 yanıtı sonucun hazır olduğunu belirtir; 202 dosyanın hâlâ denetlendiğini (processing) belirtir ve sonuç GET /v1/uploads/{upload_id} ile alınır. Durum pending değerine dönerse (bir API örneğinin yeniden başlatılması denetimi yarıda kesti) complete adımını yeniden gönderin. Sonuç alındıktan sonra complete adımını yinelemek aynı sonucu döndürür. Eksik parçalar 409 uploads.incomplete (details.missing) döndürür. Oluşturma sırasında bildirilenden farklı bir sha256 ya da alınan bir parçadan farklı bir parts[].etag 422 uploads.checksum_mismatch döndürür. Kullanılmayan hazır bir yükleme 24 saat yaşar. 1.62.0 sürümünde eklendi.

Kimlik doğrulama

API anahtarını Authorization başlığında gönderin: Authorization: Bearer <anahtar>.

Yol parametreleri

  • upload_idstringzorunlu

    Yükleme kimliği (upl_ ve ardından 32 onaltılık karakter).

    length ≤ 64

Başlık parametreleri

  • Idempotency-Keystring

    Bir yazma işleminin güvenli yeniden denenmesi için idempotency anahtarı (aynı isteğin tekrarı işlemi ikinci kez çalıştırmaz): 1–255 yazdırılabilir ASCII karakteri; her mantıksal işlem için bir UUID v4 önerilir. 24 saat içinde aynı anahtarla yapılan yeniden deneme işlemi tekrar çalıştırmaz: kaydedilmiş yanıtı (durum, başlıklar ve gövde) Idempotency-Replayed: true başlığıyla döndürür. Aynı anahtar farklı bir yöntem, yol, Content-Type ya da gövdeyle kullanılırsa 409 api.idempotency_mismatch döner; ilk istek hâlâ çalışırken Retry-After: 1 ile birlikte 409 api.idempotency_in_progress döner. 5xx ya da 429 yanıtından sonra anahtar serbest bırakılır ve yeniden deneme işlemi tekrar çalıştırır. Anahtar kuruluşa ve çağırana özgüdür (API anahtarı, kullanıcı ya da özel kaynak anahtarı).

    length ≥ 1, length ≤ 255

İstek gövdesi

application/json

Nesne: UploadComplete

  • sha256stringzorunlu

    Dosyanın tamamının SHA-256 değeri.

  • partsarray of UploadPartRef

    İsteğe bağlı parça denetimi: her parçanın PUT …/parts/{n} yanıtında döndürülen ETag değeri.

    items ≤ 1000

Yanıtlar

200Sonuç hazır: `ready` ya da `rejected`.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

  • Idempotency-Replayed

    true: yanıt bu Idempotency-Key için kaydedilmiş yanıttan yeniden verildi; işlem tekrar çalışmadı.

application/json

Nesne: Upload

  • idstringzorunlu

    Yüklemenin kimliği (upl_ ve ardından 32 onaltılık karakter).

  • purposeUploadPurposezorunlu
  • filenamestringzorunlu

    Dosya adı (klasörler olmadan).

  • content_typestringzorunlu

    Bildirilen içerik türü; bildirilmediyse boş.

  • sizeinteger (int64)zorunlu

    Bayt cinsinden dosya boyutu.

  • sha256string | nullzorunlu

    Oluşturmada ya da complete sırasında bildirilen, dosyanın SHA-256 değeri; henüz bilinmiyorsa null.

  • statusUploadStatuszorunlu
  • part_sizeinteger (int64)zorunlu

    Sonuncusu dışındaki her parçanın boyutu (5 ile 100 MiB arası).

  • part_countintegerzorunlu

    Parça sayısı.

    ≥ 1, ≤ 1000

  • parts_receivedintegerzorunlu

    Alınan parça sayısı.

    ≥ 0

  • partsarray of UploadPartzorunlu

    Numaraya göre alınan parçalar (POST /v1/uploads yanıtında boş).

  • reject_reasonstring | nullzorunlu

    Ret nedeni (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Değer listesi genişleyebilir; reddedilmediyse null.

  • reject_detailsobject | nullzorunlu

    Ret ayrıntıları (uzantı, bildirilen ve algılanan biçim, sağlama toplamları); reddedilmediyse null.

  • created_atstring (date-time)zorunlu

    Yüklemenin oluşturulma zamanı.

  • expires_atstring (date-time)zorunlu

    Yüklemeyi tamamlamak ve hazır olduğunda kullanmak için son tarih.

  • completed_atstring (date-time) | nullzorunlu

    Denetimin bittiği zaman (ready ya da rejected).

  • consumed_atstring (date-time) | nullzorunlu

    Yüklemenin kullanıldığı zaman (bir kart, bir arşiv ya da bir içe aktarma tarafından).

202Dosya hâlâ denetleniyor (`processing`).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

  • Idempotency-Replayed

    true: yanıt bu Idempotency-Key için kaydedilmiş yanıttan yeniden verildi; işlem tekrar çalışmadı.

application/json

Nesne: Upload

  • idstringzorunlu

    Yüklemenin kimliği (upl_ ve ardından 32 onaltılık karakter).

  • purposeUploadPurposezorunlu
  • filenamestringzorunlu

    Dosya adı (klasörler olmadan).

  • content_typestringzorunlu

    Bildirilen içerik türü; bildirilmediyse boş.

  • sizeinteger (int64)zorunlu

    Bayt cinsinden dosya boyutu.

  • sha256string | nullzorunlu

    Oluşturmada ya da complete sırasında bildirilen, dosyanın SHA-256 değeri; henüz bilinmiyorsa null.

  • statusUploadStatuszorunlu
  • part_sizeinteger (int64)zorunlu

    Sonuncusu dışındaki her parçanın boyutu (5 ile 100 MiB arası).

  • part_countintegerzorunlu

    Parça sayısı.

    ≥ 1, ≤ 1000

  • parts_receivedintegerzorunlu

    Alınan parça sayısı.

    ≥ 0

  • partsarray of UploadPartzorunlu

    Numaraya göre alınan parçalar (POST /v1/uploads yanıtında boş).

  • reject_reasonstring | nullzorunlu

    Ret nedeni (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Değer listesi genişleyebilir; reddedilmediyse null.

  • reject_detailsobject | nullzorunlu

    Ret ayrıntıları (uzantı, bildirilen ve algılanan biçim, sağlama toplamları); reddedilmediyse null.

  • created_atstring (date-time)zorunlu

    Yüklemenin oluşturulma zamanı.

  • expires_atstring (date-time)zorunlu

    Yüklemeyi tamamlamak ve hazır olduğunda kullanmak için son tarih.

  • completed_atstring (date-time) | nullzorunlu

    Denetimin bittiği zaman (ready ya da rejected).

  • consumed_atstring (date-time) | nullzorunlu

    Yüklemenin kullanıldığı zaman (bir kart, bir arşiv ya da bir içe aktarma tarafından).

401Kimlik bilgisi gönderilmedi (ne oturum çerezi ne de API anahtarı) ya da anahtar bulunamadı.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

403İşleme izin verilmiyor: rol yetersiz, koleksiyona ya da karta erişim yok, istek “View as” modunda çalışıyor ya da kuruluş askıya alınmış veya silinmiş (`detail`, `code: org_suspended | org_deleted` içeren bir nesnedir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

404Nesne yok ya da size açık değil. API, erişimi kısıtlı bir nesnenin var olduğunu belli etmez.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

409Nesnenin durumu işleme izin vermiyor; örneğin yinelenen bir kayıt, süren bir dizinleme ya da zaten işlenmiş bir iş.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

410Nesne vardı ama artık kullanılamıyor: bağlantı kullanıldı ya da süresi doldu veya dosya saklama süresinin sonunda silindi.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

422Geçerlilik hatası: gövde ya da parametreler şemaya uymuyor (`detail` geçerlilik hatalarının listesidir) ya da bir parametre değeri aralığın dışında (`detail` bir iletidir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

429Çok fazla istek (`api.rate_limited`), kuruluşun dakika, gün ya da ay kotası doldu (`api.quota_exceeded`; `error.details` alanında `quota`, `limit` ve `reset_at` bulunur), kuruluşun limitine ulaşıldı ya da yanıt hizmeti meşgul (`answers.engine_busy`). `Retry-After` başlığındaki süre kadar bekleyin.

Yanıt başlıkları

  • Retry-After

    İsteği yeniden denemeden önce beklenmesi gereken saniye sayısı.

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

Hata kodları

Bu uç noktanın, her isteğin genel kodlarının yanı sıra error.code alanında döndürebileceği kodlar.

Güvenli yeniden denemeler

Her POST ve PATCH isteğiyle bir Idempotency-Key başlığı (örneğin bir UUID) gönderin. Aynı anahtarla 24 saat içinde yapılan yeniden deneme, isteği yeniden çalıştırmak yerine kaydedilmiş yanıtı döndürür.

Hız sınırları

Yanıtlarda RateLimit ve RateLimit-Policy başlıklarıyla birlikte daha eski X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 yanıtında saniye cinsinden Retry-After başlığı vardır: bekleyin ve yeniden deneyin.

← uploads · API başvurusu