Facebook oEmbed

Facebook oEmbed 端點可用於取得粉絲專頁、貼文和影片的內嵌 HTML 和基本中繼資料，以利在其他網站或應用程式中顯示這些項目。

oEmbed 產品已經改成 oEmbed 讀取功能。如果您實作 oEmbed 產品的時間在 2021 年 6 月 8 日之前，請在 2021 年 9 月 7 日前完成 oEmbed 讀取功能的應用程式審查。如果您未在 2021 年 9 月 7 日前通過 oEmbed 讀取功能的審查，您實作的 oEmbed 將無法載入。

常見用途

在傳訊應用程式中轉譯 Facebook 粉絲專頁、貼文和影片。
在網站和部落格中內嵌 Facebook 粉絲專頁、貼文和影片。
在內容管理系統中轉譯 Facebook 粉絲專頁、貼文和影片。

端點

端點	說明
`GET /oembed_page`	取得 Facebook 粉絲專頁的內嵌 HTML 和基本中繼資料。
`GET /oembed_post`	取得 Facebook 貼文的內嵌 HTML 和基本中繼資料。
`GET /oembed_video`	取得 Facebook 影片的內嵌 HTML 和基本中繼資料。

需求

限制

Facebook oEmbed 端點的用途僅是在網站和應用程式中內嵌 Facebook 內容。不得用於其他用途。嚴禁從端點將中繼資料和粉絲專頁、貼文或影片內容（或是其他衍生作品）用於提供粉絲專頁、貼文，或影片前端檢視之外的其他用途。禁止範圍包括使用、操縱、擷取或保留中繼資料和內容，包括但不限於以中繼資料衍生關於粉絲專頁、貼文和影片的資訊，做為分析之用。

應用程式審查

您的應用程式必須通過 oEmbed 讀取功能的應用程式審查，才能使用 oEmbed。

在提供能讓我們測試 Oembed 讀取功能的網址表單欄位中，使用 oEmbed 端點取得我們官方 Facebook 粉絲專頁或 Instagram 頁面上的任何公開貼文或影片的內嵌 HTML（或取得任一粉絲專頁本身的內嵌 HTML）。將傳回的內嵌 HTML 加到您自己的粉絲專頁，您將在其中顯示 oEmbed 內容並在表單欄位中輸入該粉絲專頁的網址。

oEmbed 讀取功能通過審查後，您就可以使用粉絲專頁、貼文或影片的專屬網址內嵌這些內容。

存取權杖

Facebook oEmbed 端點必須要有應用程式存取權杖（建議）或用戶端存取權杖。

應用程式存取權杖

如果您的應用程式必須使用後端伺服器，建議存取 oEmbed 端點時使用應用程式存取權杖。速限取決於要求所含的權杖類型，而應用程式權杖速限能接受的要求上限是每天 500 萬個。

如需瞭解產生應用程式存取權杖的操作說明，請參閱《存取權杖》說明文件中的應用程式權杖一節。

請注意，絕對不能將應用程式存取權杖用於用戶端。一定要將應用程式存取權杖妥善保存在您的伺服器上。如果您的應用程式必須在用戶端使用權杖，請使用用戶端存取權杖。

用戶端存取權杖

如果您的應用程式必須在行動裝置或網頁瀏覽器等用戶代理程式存取 oEmbed 端點，則應用程式必須使用用戶端存取權杖，且必須遵守用戶端權杖速限。

若要取得用戶端存取權杖，請登入應用程式主控板，依序前往設定 > 進階 > 帳號安全 > 用戶端權杖。

與應用程式存取權杖不同的是，用戶端存取權杖無法單獨用於 oEmbed 端點要求，必須結合應用程式編號才能使用。若要這樣做，請將權杖附加到應用程式編號結尾，並以豎線符號分隔（|）：

{app-id}|{client-token}

例如：

access_token=1234|5678

速限

速限取決於應用程式包含在每個要求中的存取權杖類型。

應用程式權杖速限

應用程式若必須使用應用程式存取權杖，能接受的要求上限是每 24 小時 500 萬個。

用戶端權杖速限

用戶端權杖速限遠低於應用程式權杖速限。速限因應用程式活動而異，因此我們不會公佈實際速限。不過，除非您的應用程式出現類機器人的行為，像是批次處理數千個要求，或者每個代理程式或應用程式用戶會傳送數千個要求，否則您都可以放心使用應用程式，不至於會達到速限。

取得內嵌 HTML

要取得粉絲專頁、貼文或影片的內嵌 HTML，請發送要求至對應粉絲專頁、貼文或影片的 oEmbed 端點：

目標	端點和查詢結構
粉絲專頁	`GET /oembed_page?url={url}&access_token={access-token}`
貼文	`GET /oembed_post?url={url}&access_token={access-token}`
影片	`GET /oembed_video?url={url}&access_token={access-token}`

將 {url} 改為您所查詢之粉絲專頁、貼文或影片的網址，再將 {access-token} 改為您的應用程式或用戶端存取權杖（或使用 HTTP 標頭將權杖傳送給我們）。如果您使用用戶端存取權杖，必須使用豎線符號將權杖與應用程式編號結合，否則要求將會失敗。

如果成功，API 會以 JSON 物件回應，其中將包含粉絲專頁、貼文或影片的内嵌 HTML，以及與粉絲專頁、貼文或影片相關的其他資料。內嵌 HTML 將會指派至 html 屬性。

請參閱各端點的參考資料，取得一份查詢字串參數清單，加入這些參數就能擴大要求範圍。您也可在任何要求中加入 fields 查詢字串參數，指定您要傳回的欄位。如果省略，回應會包含所有預設欄位。

粉絲專頁要求範例

curl -i -X GET \
 "https://graph.facebook.com/v19.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC&access_token=96481..."

回應範例

為方便閱讀，會以刪節號（...）截斷部分數值。

{
  "provider_url": "https://www.facebook.com",
  "provider_name": "Facebook",
  "height": 500,
  "html": "<div id=\"fb-root\"></div><script async=\"1\" defer=...",
  "type": "rich",
  "version": "1.0",
  "width": 340
}

網址格式

url 查詢字串參數接受下列網址格式：

粉絲專頁

https://www.facebook.com/{page-name}
https://www.facebook.com/{page-id}

貼文

https://www.facebook.com/{page-name}/posts/{post-id}
https://www.facebook.com/{username}/posts/{post-id}
https://www.facebook.com/{username}/activity/{activity-id}
https://www.facebook.com/photo.php?fbid={photo-id}
https://www.facebook.com/photos/{photo-id}
https://www.facebook.com/permalink.php?story_fbid={post-id}&id={page-or-user-id}
https://www.facebook.com/media/set?set={set-id}
https://www.facebook.com/questions/{question-id}
https://www.facebook.com/notes/{username}/{note-url}/{note-id}

影片

https://www.facebook.com/{page-name}/videos/{video-id}/
https://www.facebook.com/{username}/videos/{video-id}/
https://www.facebook.com/video.php?id={video-id}
https://www.facebook.com/video.php?v={video-id}

SDK JS

內嵌 HTML 預設包含 sdk.js JavaScript 程式庫參照。若要取得不含參照的內嵌 HTML 以利分別載入，請加入 omitscript=true 查詢字串參數。

使用標頭傳送存取權杖

如果不想在要求的查詢字串中加入存取權杖，可以改用 Authorization HTTP 標頭傳送給我們。

Authorization: Bearer {access-token}

例如：

curl -i -X GET \
  "https://graph.facebook.com/v19.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC" \
  --header "Authorization: Bearer 96481..."