Bağlantı önizleme (unfurl)¶

Unfurl, tek bir URL'yi bir mesajın o URL için göstereceği bağlantı önizlemesine dönüştürür. API, URL'yi TEBHOS unfurl hizmetine iletir; bu hizmet siteye özel bir çözümleyici seçer ya da sayfanın Open Graph ve meta etiketlerini okumaya geri döner. Mesajlara eklenen bağlantı önizlemeleri için de aynı çözümleyici zinciri kullanılır.

Unfurl gömme nesnesi¶

URL gömmesini çözümle ucunun yanıtıdır. Bu, mesaj gömmelerinin bir listesi değil, düz bir önizleme nesnesidir.

Yapı¶

Alan	Tür	Açıklama
url	string	Çözümlenen URL
title	?string	Sayfanın veya medyanın başlığı
description	?string	Sayfa açıklaması
image	?string	Önizleme görselinin URL'si
site_name	?string	Sitenin veya sağlayıcının adı
author	?string	Sayfa bir yazar adı sunuyorsa yazar adı
type	?string	Önizleme türü; örneğin `link`, `video`, `article`, `social` veya `gifv`
video	?unfurl video nesnesi	Çözümleyici bir video bulduysa oynatılabilir video ayrıntıları
color	?string	Tema rengi ipucu; örneğin `#1DA1F2`
favicon	?string	Sitenin favicon URL'si

Metin alanları (title, description, site_name, author) döndürülmeden önce temizlenir.

Unfurl video nesnesi¶

Alan	Tür	Açıklama
url	string	Video URL'si
width	?integer	Video genişliği
height	?integer	Video yüksekliği
embed_url	?string	Gömülebilir oynatıcı URL'si (örneğin bir YouTube iframe URL'si)

Örnek¶

{
  "url": "https://example.com/article",
  "title": "Example article",
  "description": "A short description taken from the page metadata.",
  "image": "https://example.com/cover.png",
  "site_name": "Example",
  "author": null,
  "type": "article",
  "video": null,
  "color": null,
  "favicon": "https://example.com/favicon.ico"
}

Site çözümleyicileri¶

Site	Eşleşen URL	Notlar
YouTube	Bir video kimliği ayrıştırılabildiğinde `youtube.com`, `www.youtube.com`, `m.youtube.com`, `music.youtube.com`, `youtube-nocookie.com`, `www.youtube-nocookie.com`, `youtu.be`	YouTube Data API'yi kullanır. Örneğin (instance) bir YouTube API anahtarına ihtiyacı vardır; anahtar yoksa önizleme üretilmez. Video olmayan YouTube sayfaları genel çözümleyiciyi kullanır
Klipy	Yolu `/gif`, `/gifs`, `/clip` veya `/clips` altında olan `klipy.com` ve `www.klipy.com`	Klipy API'yi kullanır ve `gifv` önizlemesi döndürür. Örneğin (instance) bir Klipy API anahtarına ihtiyacı vardır
Wikipedia	`.wikipedia.org/wiki/` içeren her URL	Wikipedia REST özetini kullanır; başarısız olursa genel çözümleyiciye döner
Twitter / X	`twitter.com` veya `x.com` içeren her URL	Site adı `Twitter` ya da `X`, türü `social` olarak ayarlanan ve yazarı yoldan türetilen genel bir tarama yapar; başarısız olursa genel çözümleyiciye döner
Genel	Diğer tüm URL'ler	Bir HTML sayfasının ilk 500 KB'ından `og:`, `twitter:` ve standart meta etiketlerini okur. HTML olmayan bir yanıt yalın bir `{url, type: "link"}` önizlemesi üretir

Ağ politikası¶

API, bir URL'yi çözümlemeden önce şu durumlarda reddeder: URL ayrıştırılamıyorsa, şeması http veya https değilse ya da ana makinesi yerel veya özel bir adresse (localhost, loopback, link-local, özel IPv4 aralıkları, bulut metadata ana makineleri).

Unfurl hizmeti her URL'ye ikinci bir denetim uygular: URL en fazla 8192 karakter olmalı ve kontrol karakteri içermemeli, kullanıcı bilgisi taşımamalı, 0 bağlantı noktasını kullanmamalı, geçerli bir genel ana makine adına sahip olmalı ve yalnızca genel IP adreslerine çözümlenmelidir. Bir sayfa getirme işlemi 5 saniye sonra zaman aşımına uğrar ve en fazla 3 yönlendirmeyi izler. Çözümlemenin tamamı 20 saniye sonra bırakılır.

Önbellek davranışı¶

Başarılı sonuçlar, birebir aynı URL başına bir saat önbelleğe alınır. Bu süre içinde tekrarlanan bir istek siteyle iletişime geçilmeden önbellekten yanıtlanır.

URL gömmesini çözümle¶

GET /embed

Verilen URL'yi çözümler ve bir unfurl gömme nesnesi döndürür. Kimlik doğrulama gerekmez ve hiçbir izin uygulanmaz.

Sorgu parametreleri¶

Alan	Tür	Açıklama
url	string	Çözümlenecek mutlak `http` veya `https` URL'si

Yanıt¶

Durum	Gövde	Koşul
200	unfurl gömme nesnesi	URL çözümlendi
400	hata yanıtı	`url` eksik, hatalı biçimli, ağ politikası tarafından engellenmiş, getirilemiyor ya da ilgili API anahtarı olmayan bir örnekte (instance) YouTube/Klipy URL'si (`BAD_REQUEST`)
500	hata yanıtı	Unfurl hizmeti kullanılamıyor veya içeride başarısız oldu (`INTERNAL_SERVER_ERROR`)

Yan etkiler¶

Çözümleme, URL'yi ve yukarıda listelenen sağlayıcı API'lerini getirebilir. Hiçbir mesaj oluşturmaz.

Hız sınırı¶

Bu yolun kendine özgü bir kovası yoktur. Kimliği doğrulanmış istekler, Hız sınırları bölümünde açıklanan istemci başına genel sınıra sayılır; kimliği doğrulanmamış GET istekleri sayılmaz.

Örnek¶

curl -G "https://tebhos.com/api/v1/embed" \
  --data-urlencode "url=https://example.com/article"