Ek yüklemeleri¶

İstemci normalde önce her dosyayı yükler, ardından mesajı oluştururken ona başvurur. Akış üç adımdan (büyük dosyalar için dört adımdan) oluşur:

1. Dosyalar için bir yükleme planı isteyin.
2. Her dosyanın baytlarını PUT ile kendi yükleme URL'sine veya her parçayı kendi parça URL'sine gönderin.
3. Çok parçalı bir yükleme için yüklemeyi tamamlayın.
4. Döndürülen yükleme anahtarlarıyla mesajı oluşturun.

Küçük dosyalar bunun yerine multipart/form-data olarak doğrudan mesaj isteğinin içinde gönderilebilir; bkz. Çok parçalı gövde.

Ek yüklemeleri kullanıcı oturumlarını ve bot token'larını kabul eder. Çağıranın bir sunucu kanalında VIEW_CHANNEL, SEND_MESSAGES ve ATTACH_FILES izinlerine sahip olması, zaman aşımında olmaması ve özel bir kanalın alıcısı olması gerekir.

Boyut sınırları¶

Tek bir dosyanın en büyük boyutu, yükleyenin planına ve sunucunun takviye seviyesine bağlıdır. Geçerli sınır ikisinden büyük olanıdır.

Özel bir kanalın takviye seviyesi yoktur; dolayısıyla orada yalnızca hesap sınırı geçerlidir. Sınırı aşan bir dosya, plan istendiğinde 400 BAD_REQUEST ile reddedilir. Bir mesaj en fazla 10 ek taşıyabilir.

Yükleme planı isteme¶

POST /channels/{channel_id}/attachments

Aynı anda 1 ile 10 dosya için yükleme URL'leri ister.

Hız sınırı: channel:attachment:upload, hesap ve kanal başına 10 saniyede 10.

Yanıt, istenen her dosya için bir giriş içeren {"attachments": [...]} biçimindedir:

curl -X POST https://tebhos.com/api/v1/channels/1489002177550843904/attachments \
  -H "Authorization: Bearer $TEBHOS_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"attachments": [{"id": 0, "filename": "photo.png", "file_size": 48213, "content_type": "image/png"}]}'

{
  "attachments": [
    {
      "id": 0,
      "upload_mode": "singlepart",
      "filename": "photo.png",
      "upload_filename": "3f6c2a8e-6d1b-4f0e-9a52-1c7f4b2d9e10",
      "upload_url": "https://storage.example.com/attachments/1489002177550843904/1489002299998765056/photo.png?X-Amz-Signature=...",
      "file_size": 48213,
      "content_type": "image/png",
      "attachment_id": "3f6c2a8e-6d1b-4f0e-9a52-1c7f4b2d9e10",
      "storage_key": "attachments/1489002177550843904/1489002299998765056/photo.png",
      "url": "https://cdn.tebhos.com/attachments/1489002177550843904/1489002299998765056/photo.png"
    }
  ]
}

Parça boyutu¶

Çok parçalı bir plan yaklaşık 20 parçayı hedefler: parça boyutu, dosya boyutunun 20'ye bölünüp tam bir MiB'ye yukarı yuvarlanmasıyla bulunur ve hiçbir zaman 10 MiB'nin altında olmaz. n numaralı parça (n - 1) × part_size baytından bir sonraki parçaya kadar olan kısmı kapsar; son parça kalanı tutar.

Tek dosyalık varyant¶

POST /channels/{channel_id}/attachments/upload-url, {"filename": string, "content_type": string, "size": integer} gövdesiyle tek bir dosya için plan ister. attachment_id, upload_url, storage_key, url, expires_in (saniye) ve max_size döndürür. Aynı kovayı ve sınırları paylaşır.

Baytları aktarma¶

upload_url adresine, gövdesi dosyanın baytları olan bir PUT isteği gönderin. Authorization başlığı göndermeyin ve URL'nin yolunu veya sorgu dizesini değiştirmeyin.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

Tek bir yükleme URL'si 5 dakika (300 saniye), bir parça URL'si 1 saat geçerlidir. Süresi dolmuş bir URL yenilenemez; yeni bir plan isteyin.

Çok parçalı bir dosya için her parçanın baytlarını PUT ile kendi parça URL'sine gönderin; bunu istediğiniz sırada ve dilerseniz paralel yapabilirsiniz.

Yükleme URL'sinin nereyi gösterdiği örneğe (instance) bağlıdır: önceden imzalanmış yüklemelerde (örnek özelliklerinde presigned_attachment_uploads true) imzalı bir nesne depolama URL'sidir; aksi halde API'nin kendisi altındaki bir yoldur. İstemci akışı her iki durumda da aynıdır.

Çok parçalı yüklemeyi tamamlama¶

POST /channels/{channel_id}/attachments/complete

Bir veya daha fazla çok parçalı yüklemenin yüklenmiş parçalarını dosyalarında birleştirir. Tüm parçalar gönderildikten sonra ve mesaj oluşturulmadan önce çağırın.

Hız sınırı: channel:attachment:upload (yükleme planlarıyla paylaşılır), hesap ve kanal başına 10 saniyede 10.

Sunucu her giriş için yüklemenin çağıran tarafından bu kanalda çok parçalı olarak planlandığını denetler, depolamadaki parçaları listeler ve birleştirir. Birleştirilen dosya ardından meta veri onayı ile aynı işlemden geçer: boyutu çağıranın sınırına göre, SHA-256 özeti engellenen dosyalar listesine göre denetlenir; görüntü boyutları ve bir yer tutucu hesaplanır. Ayrı bir onay çağrısı gerekmez.

Yanıt, tamamlanan her yükleme için bir giriş içeren {"uploads": [{"upload_filename": string}]} biçimindedir.

curl -X POST https://tebhos.com/api/v1/channels/1489002177550843904/attachments/complete \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uploads": [{"upload_filename": "3f6c2a8e-6d1b-4f0e-9a52-1c7f4b2d9e10", "upload_id": "2~abc..."}]}'

İsteğe bağlı meta veri onayı¶

POST /channels/{channel_id}/attachments/{attachment_id}/confirm

Yüklemeden sonra istemci, bekleyen ek üzerine meta veri kaydedebilir. Her alan isteğe bağlıdır. Bu adım zorunlu değildir; aynı meta veriler mesaj oluşturulurken de gönderilebilir.

Yüklemeyi sahiplenme¶

Yüklenen her dosyaya Mesaj oluşturma içinde, upload_filename değerini taşıyan nesnelerden oluşan bir attachments dizisiyle başvurun:

{
  "content": "Here is the photo",
  "attachments": [
    {
      "upload_filename": "3f6c2a8e-6d1b-4f0e-9a52-1c7f4b2d9e10",
      "width": 1280,
      "height": 720,
      "flags": 0
    }
  ]
}

Burada gönderilen meta veriler yalnızca onay adımında ayarlanmamış alanları doldurur. Alternatif olarak attachment_ids (upload_filename değerlerinden oluşan bir dizi) ve spoiler_attachment_ids gönderin.

Bir yükleme anahtarı tek kullanımlıktır ve onu isteyen hesaba aittir. Bilinmeyen, zaten kullanılmış veya başka bir hesaba ait bir anahtar hata verilmeden atlanır; bu nedenle her dosyanın eklendiğini doğrulamak için döndürülen mesajın attachments alanını denetleyin. Yalnızca yükleme yapmak mesaj oluşturmaz ve hiçbir Gateway olayı göndermez.

Saklama süresi¶

Saklanan bir ek, boyutuna bağlı bir süre boyunca tutulur: 5 MiB'ye kadar olan dosyalar yaklaşık üç yıl tutulur ve süre boyutla birlikte azalarak 500 MiB'lik dosyalar için 14 güne iner. Süresi dolan ekler otomatik olarak kaldırılır.

Profil ve sunucu görüntüleri¶

Avatarlar, afişler, sunucu simgeleri, emojiler ve çıkartmalar kendi yükleme URL'si yollarını kullanır; bunlar geçerli kullanıcı, sunucular, sunucu emojileri ve sunucu çıkartmaları sayfalarında açıklanır.

Yayın önizlemeleri¶

Yayın önizlemesi, bir ekran paylaşımına eklenmiş bir JPEG görüntüsüdür. Ek akışını değil Yayınlar API'sini kullanır. Önizleme satır içi olarak veya POST /streams/{stream_key}/preview/upload-url ile alınan bir yükleme URL'si üzerinden gönderilebilir; görüntü en fazla 1000000 bayt olmalıdır ve yükleme URL'si bir gün geçerlidir.

Hatalar¶

API istekleri standart hata yanıtını döndürür. Nesne depolamasına yapılan başarısız bir PUT, depolama sağlayıcısının kendi hata biçimini döndürür.