Instagram oEmbed

您可以查詢 Instagram oEmbed 端點，用於取得 Instagram 貼文的內嵌 HTML 和基本中繼資料，將貼文顯示在其他的網站或應用程式中。支援相片、影片、連續短片和指南貼文。

常見用途

在傳訊應用程式中轉譯貼文。
在網站和部落格中內嵌貼文。
在內容管理系統中轉譯貼文。

端點

端點	說明
`GET /instagram_oembed`	取得 Instagram 貼文的內嵌 HTML 和基本中繼資料。

必備條件

限制

Instagram oEmbed 端點只能用於在網站和應用程式中內嵌 Instagram 內容。不得用於其他用途。嚴禁從端點將中繼資料和粉絲專頁、貼文或影片內容（或其他衍生作品）用於提供粉絲專頁、貼文，或影片前端檢視之外的其他用途。禁止範圍包括使用、操縱、擷取或保留中繼資料和內容，包括但不限於以中繼資料衍生關於粉絲專頁、貼文和影片的資訊，做為分析之用。
不支援使用不公開、停用和有年齡限制的 Instagram 帳號發表貼文。
不支援具備已停用內嵌元素的帳號。
不支援限時動態。
不支援 Shadow DOM。

應用程式審查

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

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

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

存取權杖

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

應用程式存取權杖

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

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

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

用戶端存取權杖

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

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

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

{app-id}|{client-token}

例如：

access_token=1234|5678

速限

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

應用程式權杖速限

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

用戶端權杖速限

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

取得內嵌 HTML

要取得 Intagram 貼文的内嵌 HTML，請發送要求至：

GET /instagram_oembed?url={url}&access_token={access-token}

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

如果成功，API 會以 JSON 物件回應，其中將包含貼文的内嵌 HTML 和其他資料。指派內嵌 HTML 至 html 屬性。

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

要求範例

curl -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."

回應範例

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

{
  "version": "1.0",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/",
  "type": "rich",
  "width": 658,
  "html": "<blockquote class=\"instagram-media\" data-instgrm-ca...",
  "thumbnail_width": 640,
  "thumbnail_height": 640
}

網址格式

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

https://www.instagram.com/p/{media-shortcode}/
https://www.instagram.com/tv/{media-shortcode}/https://www.instagram.com/{username}/guide/{slug}/{guide_id}

內嵌 JS

內嵌 HTML 包含 Instagram embed.js JavaScript 程式庫的參考。程式庫載入時會掃描頁面以找出貼文的 HTML，並且產生完整轉譯的貼文。如果想分別載入程式庫，請在要求中加入 omitscript=true 查詢字串參數。要手動初始化內嵌 HTML，請在載入程式庫後呼叫 instgrm.Embeds.process() 函式。

貼文大小

內嵌貼文為回應式，會根據容器大小調整。也就是說，其高度會隨著容器寬度和文字長度而改變。您可以在要求中加入 maxwidth 查詢字串參數，用於設定最大寬度。

取得縮圖

建議您盡可能轉譯所有貼文的內嵌 HTML。如果做不到，可以取得貼文的縮圖圖像網址，改為轉譯這個網址。如果這樣做，您仍須在圖像旁清楚註明出處，包括原作者和 Instagram 的出處，以及您所查詢之 Instagram 貼文的連結。

若要取得貼文的縮圖網址和出處資訊，請發送要求至：

GET /instagram_oembed
  ?url={url}
  &maxwidth={maxwidth}
  &fields=thumbnail_url,author_name,provider_name,provider_url
  &access_token={access-token}

將 {url} 改為您所查詢之 Instagram 貼文的網址，再將 {maxwidth} 改為要轉譯之縮圖的最大大小，並將 {access-token} 改為應用程式或用戶端存取權杖。

要求範例

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN&maxwidth=320&fields=thumbnail_url%2Cauthor_name%2Cprovider_name%2Cprovider_url&access_token=96481..."

回應範例

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

{
  "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.288...",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/"
}

使用標頭傳送存取權杖

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

Authorization: Bearer {access-token}

例如：

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