Facebook oEmbed

Facebook oEmbed 端點可以用來獲取專頁、帖子和影片的嵌入式 HTML 和基本元數據，以便在其他網站或應用程式中顯示。

oEmbed 產品已由 oEmbed Read 功能取代。如果您在 2021 年 6 月 8 日之前執行 oEmbed 產品，則必須在 2021 年 9 月 7 日之前完成 oEmbed Read 功能的應用程式審查。如果您在 2021 年 9 月 7 日之前尚未獲准使用 oEmbed Read 功能，則您的 oEmbed 操作將無法載入。

常見用途

在訊息應用程式中顯示 Facebook 專頁、帖子和影片。
在網站和網誌中嵌入 Facebook 專頁、帖子和影片。
在內容管理系統中顯示 Facebook 專頁、帖子和影片。

端點

端點	說明
`GET /oembed_page`	獲取 Facebook 專頁的內嵌 HTML 和基本元數據。
`GET /oembed_post`	獲取 Facebook 帖子的內嵌 HTML 和基本元數據。
`GET /oembed_video`	獲取 Facebook 影片的內嵌 HTML 和基本元數據。

必要條件

限制

Facebook oEmbed 端點僅供用於在網站和應用程式中嵌入 Facebook 內容。這些端點不可用於其他用途。嚴禁將來自端點的元數據、專頁、帖子或影片內容（或其衍生內容）用於提供專頁、帖子或影片前端檢視以外的其他用途。此限制涵蓋使用、操控、擷取或保留元數據和內容的行為，包括但不限於透過元數據獲取專頁、帖子和影片資訊以作分析用途。

應用程式審查

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

填寫提供用於測試 Oembed Read 的網址表格欄位時，請使用 oEmbed 端點獲取我們官方 Facebook 專頁或 Instagram 專頁上任何一個公開帖子或影片的內嵌 HTML（或者獲取 Facebook 或 Instagram 專頁的內嵌 HTML）。將傳回的內嵌 HTML 加到您要顯示 oEmbed 內容的專頁，然後在表格欄位中輸入這個專頁的網址。

在您獲准使用 oEmbed Read 功能後，您便可以使用相應網址來嵌入您的專頁、帖子或影片。

存取憑證

Facebook oEmbed 端點需要使用應用程式存取憑證（建議使用）或用戶端存取憑證。

應用程式存取憑證

如果您的應用程式需要使用後端伺服器，我們建議您使用應用程式存取憑證來存取 oEmbed 端點。傳輸率限制取決於要求中的憑證類型；而應用程式憑證傳輸率限制為每天最多 500 萬次要求。

如需有關產生應用程式存取憑證的指示，請查閱存取憑證文件中的應用程式憑證部分。

請注意，應用程式存取憑證不可在用戶端使用。憑證必須時刻安全地儲存在您的伺服器中。如果您的應用程式必須在用戶端使用憑證，請改用用戶端存取憑證。

用戶端存取憑證

如果應用程式必須透過流動裝置、網頁瀏覽器等用戶代理存取 oEmbed 端點，則應用程式必須使用用戶端存取憑證，並需要遵循用戶端憑證傳輸率限制。

如要獲取用戶端存取憑證，請登入您的應用程式管理中心，並前往設定 > 進階 > 帳戶安全 > 用戶端憑證。

用戶端存取憑證與應用程式存取憑證不同，您不能單單用它來要求 oEmbed 端點，並必須配合應用程式編號加以使用。如要執行此動作，將您的憑證附加至應用程式編號的尾端，並使用豎線分隔 (|)：

{app-id}|{client-token}

例如：

access_token=1234|5678

限速限制

傳輸率限制取決於每次要求中包含的應用程式存取憑證類型。

應用程式憑證傳輸率限制

使用應用程式存取憑證的應用程式每 24 小時最多可傳送 500 萬次要求。

用戶端憑證傳輸率限制

用戶端憑證傳輸率限制大幅低於應用程式憑證傳輸率限制。由於傳輸率限制視乎應用程式活動而異，所以我們沒有列出具體限制。不過，一般來說，應用程式不會超過這個限制，除非應用程式執行與 Bot 類似的行為，例如一次傳送數千次要求，或者每個代理或應用程式用戶傳送數千次要求。

獲取內嵌 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/v21.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/v21.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC" \
  --header "Authorization: Bearer 96481..."