oEmbed 規格

[ajhsu]

oEmbed

oEmbed 是一種可以讓內容嵌入至第三方網站的格式。當使用者貼上一組代表資源的網址時，簡易的 API 可以讓網站顯示嵌入內容（例如照片或影片），可以無需另外轉換資源。

原文網址

完整規格

主要的規格分為三個部分：設定、嵌入者的請求 與 提供者的回應。 一個 oEmbed 的交換會發生在 嵌入者 與 提供者 之間。

當一個 嵌入者 希望在網站上顯示一個第三方資源時，一個 提供者 必須實作 oEmbed API 來讓 嵌入者 能夠取得對應的資源。

設定

oEmbed 的設定相當簡單，提供者 必須指定一個或多個 URL scheme & API endpoint 組合。 URL scheme 描述了哪些網址是可以提供嵌入內容的，而 API endpoint 則描述了 嵌入者 可以向哪些網址請求資源。

例如：

• URL scheme: https://www.flickr.com/photos/*
• API endpoint: https://www.flickr.com/services/oembed/

URL scheme 可能包含一個或多個萬用字元（以星號標示）。萬用字元可以被放在網址的網域區段、或者位址當中。當被放在網域區段時，萬用字元只能被用在子網域。萬用字元不能被用在 scheme 當中（如果想同時支援 HTTP/HTTPS，請提供兩組 url/endpoint 組合）。

• http://www.flickr.com/photos/* 允許
• http://www.flickr.com/photos/*/foo/ 允許
• http://*.flickr.com/photos/* 允許
• http://*.com/photos/* 不允許
• *://www.flickr.com/photos/* 不允許

API endpoint 必須指向一組 HTTP/HTTPS 網址，並實作以下 API：

嵌入者請求

向 API endpoint 所發出的請求，必須是 HTTP GET 請求，並且將所有參數放進 query 參數之中。所有的參數必須被 urlencode 過（RFC 1738）。

請求參數可參考以下規格：

• url (必填): 請求嵌入資訊時所需的網址
• maxwidth (選填): 嵌入資源的寬度最大值。只對部分資源類型有效（詳見以下規格）。對於符合支援的資源類型來說，提供者必須遵守這項參數。
• maxheight (選填): 嵌入資源的高度最大值。只對部分資源類型有效（詳見以下規格）。對於符合支援的資源類型來說，提供者必須遵守這項參數。
• format (選填): 請求回應的格式。如果未指定，提供者可以回傳任何有效的格式。但當指定時，提供者必須回傳此資料格式，否則將會回傳錯誤（詳見以下錯誤代碼）。

提供者應該忽略其他未預期的參數。但同時也歡迎提供者支援額外的客製化參數。

以下為範例：

• http://flickr.com/services/oembed?url=http%3A//flickr.com/photos/bees/2362225867/
• http://flickr.com/services/oembed?url=http%3A//flickr.com/photos/bees/2362225867/&maxwidth=300&maxheight=400&format=json

備註：提供者也可以選擇使用 URL endpoint 來表示其資料格式，不一定要使用 query string 來表達。

例如：

• URL scheme: http://www.flickr.com/photos/*
• API XML endpoint: http://www.flickr.com/services/oembed.xml
• API JSON endpoint: http://www.flickr.com/services/oembed.json

在這個例子中，format 參數就可為非必要且可被忽略。當提供者制定一組 URL schene/API endpoint 時，必須明確指出 format 是該使用參數來指定，還是直接存在於既有的 URL endpoint 之中。

提供者回應

提供者所回傳的回應可以使用 JSON 或 XML 格式。這兩種格式個別有對應的方式來表達 name-value 組合。這兩種格式個別關聯到一組用來作為 Content-Type header 的回傳值的 mime-type。

JSON 回應

JSON 回應必須包含一組完整的 JSON，且必須使用 application/json 為其 mime-type。嵌入者可以透過 format=json 來請求 JSON 回應格式。

例如：

{
    "foo": "bar",
    "baz": 1
}

所需回傳的 key-value 組合在下方會提到。所有的文字必須是 UTF-8 編碼。

XML 回應

(略)

回應參數

回應可以指定其資源類型，例如 photo 或 video。每種類型都有對應的關聯參數。以下的回應參數在所有類型當中皆可以使用：

• type (必填): 資源類型。
• version (必填): oEmbed 版本號，必須為 1.0。
• title (選填): 文字標題，用來描述資源。
• author_name (選填): 資源的作者/擁有者名稱。
• author_url (選填): 資源的作者/擁有者網址。
• provider_name (選填): 資源提供者的名稱。
• provider_url (選填): 資源提供者的網址。
• cache_age (選填): 建議的資源快取存活時間，單位為秒。嵌入者可以選擇要不要使用這個參數。
• thumbnail_url (選填): 資源的縮圖網址。縮圖必須遵守 maxwidth 及 maxheight 參數。如果這個參數存在，則 thumbnail_width 及 thumbnail_height 也必須存在。
• thumbnail_width (選填): 縮圖的寬度。
• thumbnail_height (選填): 縮圖的高度。

提供者可以自行帶入任何上述文件未提及的參數（只要遵守以上的 key-value 格式），但嵌入者也可以選擇去忽略它們。嵌入者必須忽略那些他們無法理解的參數。

video 類型

link 類型

rich 類型

錯誤

提供者應該以 HTTP 狀態代碼來回傳任何錯誤狀況，以下幾個狀態代碼在 oEmbed 規格當中被定義：

• 404 Not Found: 提供者沒有針對請求的 url 參數有所回應。
• 501 Not Implemented: 提供者無法回應請求的格式。例如當請求 format=xml 但提供者不支援 XML 格式的時候。不過，我們還是鼓勵提供者可以同時提供 JSON 及 XML 兩種格式。
• 401 Unauthorized: 表示 URL 包含非公開資源。嵌入者應該提供資源的連結，而不要放入任何額外的訊息，且遵守提供者的存取控制。

安全性顧慮

當嵌入者要顯示一組 URL 的時候，他們可能需要過濾 URL scheme，例如 http, https 或 mailto；即使提供者無須考慮這些擔憂，自由地指定任何有效的網址（javascript:...），但仍可能導致 XSS 攻擊。

可探索性

oEmbed 提供者可以藉由以下 header 來選擇是否開放探索：

<link rel="alternate" type="application/json+oembed"
  href="http://flickr.com/services/oembed?url=http%3A%2F%2Fflickr.com%2Fphotos%2Fbees%2F2362225867%2F&format=json"
  title="Bacon Lollys oEmbed Profile" />
<link rel="alternate" type="text/xml+oembed"
  href="http://flickr.com/services/oembed?url=http%3A%2F%2Fflickr.com%2Fphotos%2Fbees%2F2362225867%2F&format=xml"
  title="Bacon Lollys oEmbed Profile" />

包含在 href 屬性當中的網址，必須包含完整的 oEmbed endpoint 加上 URL 以及任何有效的格式。任何其他的參數則是不必要的。

而 type 屬性則必須為 application/json+oembed (JSON) 或 text/xml+oembed (XML)。