Yanıtlar ve sınırlar¶
Medya okumalarında istek sayısına dayalı hız sınırı yoktur; bu yüzden aşağıdaki her sınır bir kaynak sınırıdır. İki medya yüzeyi hataları farklı bildirir: endpoints.media altındaki medya yolları küçük bir JSON nesnesiyle, medya vekili (/external/..., /og) ise düz metin bir gerekçeyle yanıt verir.
Medya hata yanıtı¶
Medya yolları¶
Bir görsel varlık yolundan veya /files/{key} yolundan gelen başarısız yanıtın tek alanlı bir JSON gövdesi vardır:
| Alan | Tür | Açıklama |
|---|---|---|
| error | string | Kısa, insan tarafından okunabilir bir gerekçe. Metin kararlı değildir ve yerelleştirilmiş olabilir |
Bu, HTTP API hata gövdesi değildir: code alanı yoktur. Her hata yanıtında Cache-Control: no-store ve Access-Control-Allow-Origin: * bulunur; böylece bir CDN veya tarayıcı hatayı hiçbir zaman saklamaz. 404, 422 veya 502 yanıtları ayrıca CDN-Cache-Control: no-store ve X-Content-Type-Options: nosniff taşır.
416 yanıtının gövdesi boştur. /files/{key} üzerindeki sayısal olmayan bir size, width veya height, yol çalışmadan önce istek ayrıştırma aşamasında reddedilir ve bu 400 yanıtında JSON nesnesi yerine düz metin bir gövde bulunur.
Medya vekili¶
/external/... ve /og üzerindeki her hata, neyin ters gittiğinden bağımsız olarak text/plain; charset=utf-8 gerekçe ifadesiyle bir 400'dür: geçersiz imza, reddedilen hedef, ağ hatası, başarısız kaynak durumu, izin verilmeyen içerik türü, aşırı büyük gövde veya başarısız dönüştürme. Bilinmeyen bir yol 404 döndürür.
Doğrudan aktarılan bir gövde, yanıt başladıktan sonra boyut sınırını aşarsa bağlantı sonlandırılır ve istemci kesik bir gövde görür.
İşleme sözleşmesi¶
Dallanmayı yalnızca HTTP durumuna göre yapın. Hata metnini ayrıştırmayın, karşılaştırmayın veya kalıp eşleştirmesine sokmayın: haber verilmeden yeniden ifade edilebilir veya çevrilebilir ve hataya neden olan parametreyi güvenilir biçimde adlandırmaz.
Durum kaydı¶
Medya yolları¶
| Durum | Gövde | Koşul |
|---|---|---|
| 200 | Medya baytları (HEAD için boş) |
Eksiksiz bir gösterim sunuldu |
| 206 | Seçilen baytlar (HEAD için boş) |
Tek bir bayt aralığı karşılanabilir |
| 400 | Hata nesnesi | Görsel varlık yolunda geçersiz sahip kimliği, uzantı veya özet; /files/{key} üzerinde geçersiz anahtar veya format |
| 404 | Hata nesnesi | Nesne yok ya da görsel varlık yolu görsel olmayan bir nesneyi işaret ediyor |
| 416 | Boş | Aralık karşılanamaz |
| 422 | Hata nesnesi | Nesne bir PNG, JPEG, GIF veya WebP görseli ama kodu çözülemedi veya yeniden kodlanamadı |
| 502 | Hata nesnesi | Nesne deposu okunamadı |
Medya vekili¶
| Durum | Gövde | Koşul |
|---|---|---|
| 200 | Medya baytları ya da /og üzerinde OpenGraph JSON |
Hedef alındı |
| 400 | Düz metin gerekçe | Herhangi bir hata |
| 404 | Boş | Yol bir medya vekili yolu değil |
Medya vekili, bir kaynağın hata durumunu hiçbir zaman olduğu gibi iletmez: kaynaktan gelen 403, 404 veya 5xx, 400 olarak bildirilir. Hiçbir medya yanıtı 304 değildir; koşullu istek başlıkları değerlendirilmez.
İstek ve medya sınırları¶
| Sınır | Değer |
|---|---|
| Medya vekili: vekil üzerinden aktarılan veya dönüştürülen en büyük gövde | Varsayılan 10 MiB (örnek başına yapılandırılabilir) |
Medya vekili: /og tarafından okunan HTML |
Sayfanın ilk 2 MiB'ı (örnek başına yapılandırılabilir); geri kalanı indirilmez |
| Medya vekili: izlenen yönlendirmeler | Varsayılan 5 (örnek başına yapılandırılabilir) |
| Medya vekili: izin verilen hedef içerik türleri | /external üzerinde image/*, audio/*, video/mp4, video/webm, video/ogg; /og üzerinde text/html, application/xhtml+xml |
| Medya yolları: kodu çözülmüş tek bir karedeki piksel | 64,000,000 (daha büyük kaynaklar dönüştürülmeden döndürülür) |
| Medya yolları: animasyon | Toplam 50,000,000 piksel ve 1000 kare (daha büyük animasyonlar dönüştürülmeden döndürülür) |
| Medya yolları: en büyük çıktı kenarı | Simgeler için 1024, afişler için 2400, emoji ve çıkartmalar için 512, diğer anahtarlar için 4096 |
Yükleme tarafındaki medya yolu boyut sınırları (örneğin en büyük avatar veya ek boyutu) dosya okunurken değil, yüklenirken uygulanır. Bkz. Yüklemeler.
İş kabulü¶
Medya yollarındaki görsel dönüştürmeleri sınırlı bir çalışan havuzunda çalışır (varsayılan olarak sunucunun CPU çekirdeklerinin yarısı, en az 2; örnek başına yapılandırılabilir). Tüm çalışanlar meşgul olduğunda istek başarısız olmak yerine boş bir çalışan bekler; böylece ani istek artışı reddedilmek yerine yavaşlatılır.
Aynı gösterim için eşzamanlı özdeş istekler tek bir dönüştürmeyi paylaşır ve tamamlanmış gösterimler bellek içi bir önbellekte tutulur (x-tebhos-media-cache yanıt başlığı hit, miss veya bypass bildirir). Büyük gösterimler önbelleğe alınmaz.
Süre sınırları¶
| Süre sınırı | Varsayılan | Uygulandığı yer |
|---|---|---|
| Kaynağa bağlanma zaman aşımı | 5 s | Medya vekili getirmeleri |
| Kaynak için toplam istek zaman aşımı | 10 s (örnek başına yapılandırılabilir) | Gövde dahil medya vekili getirmeleri |
Süre sınırını aşan bir medya vekili getirmesi 400 ile başarısız olur. Medya yollarının kendilerine ait istek başına süre sınırı yoktur.
Önbellek politikaları¶
| Yanıt | Cache-Control |
|---|---|
| Görsel varlık yolu, başarılı | public, max-age=31536000, immutable |
/files/{key} görseli, başarılı |
public, max-age=31536000 |
/files/{key} görsel olmayan nesne |
public, max-age=604800 |
| İmzalı harici, doğrudan aktarım | public, max-age=86400 |
| İmzalı harici, dönüştürülmüş | public, max-age=604800 |
/og |
public, max-age=3600 |
| Herhangi bir medya yolu hatası ve 416 | no-store |
Başarılı medya yolu yanıtları ayrıca CDN-Cache-Control: public, max-age=31536000 taşır.
Görsel varlık URL'lerini sonsuza dek önbelleğe almak güvenlidir: yeni bir yükleme her zaman yeni bir özet üretir; bu yüzden değişen bir avatarın URL'si de yenidir. Aynısı, anahtarları yükleme başına benzersiz bir kimlik taşıyan /files/{key} için de geçerlidir. Hiçbir medya yanıtında ETag veya Last-Modified yoktur; önbellek bir gösterimi yeniden getirerek yeniler.
Aralık yanıt başlıkları¶
Eksiksiz bir medya yolu yanıtında Accept-Ranges: bytes, gösterimin Content-Type değeri ve tam bir Content-Length bulunur. 206 yanıtı ayrıca Content-Range: bytes {start}-{end}/{size} ve seçilen bayt sayısına eşit bir Content-Length ayarlar. 416 yanıtında Content-Range: bytes */{size}, Accept-Ranges: bytes ve boş bir gövde bulunur.
HEAD, GET ile aynı aralık sözleşmesini uygular ve boş gövdeyle 206 veya 416 döndürür. Aralık saklanan nesneye değil, dönüştürülmüş gösterime uygulanır. Hangi istek aralıklarının tanındığını Bayt aralıkları tanımlar.