Nền tảng Instagram

Instagram oEmbed

Bạn có thể truy vấn điểm cuối Instagram oEmbed để lấy siêu dữ liệu cơ bản và HTML nhúng của một bài viết trên Instagram. Nhờ vậy, bạn có thể hiển thị bài viết đó trong một trang web hoặc ứng dụng khác. Hỗ trợ bài viết có ảnh, video, Thước phim và Hướng dẫn.

Cách dùng phổ biến

  • Hiển thị bài viết trong ứng dụng nhắn tin.
  • Nhúng bài viết trong trang web và blog.
  • Hiển thị bài viết trong hệ thống quản lý nội dung.

Điểm cuối

Điểm cuốiMô tả

GET /instagram_oembed

Lấy siêu dữ liệu cơ bản và HTML nhúng của bài viết trên Instagram.

Yêu cầu

Giới hạn

  • Điểm cuối Instagram oEmbed chỉ dùng để nhúng nội dung trên Instagram vào các trang web và ứng dụng. Không sử dụng điểm cuối này cho bất kỳ mục đích nào khác. Chúng tôi nghiêm cấm việc sử dụng siêu dữ liệu và nội dung trang, bài viết hoặc video (hay nội dung phái sinh) của điểm cuối này cho bất kỳ mục đích nào khác ngoài cung cấp giao diện xem trang, bài viết hoặc video cho người dùng. Quy định cấm này áp dụng cho việc sử dụng, thao tác, trích xuất hoặc duy trì siêu dữ liệu và nội dung, bao gồm nhưng không giới hạn ở thông tin lấy được về trang, bài viết và video từ các siêu dữ liệu để dùng cho mục đích phân tích.
  • Không hỗ trợ bài viết trên tài khoản Instagram riêng tư, không hoạt động và bị hạn chế độ tuổi.
  • Không hỗ trợ các tài khoản có Nội dung nhúng bị vô hiệu hóa.
  • Không hỗ trợ tin.
  • Không hỗ trợ Shadow DOM.

Xét duyệt ứng dụng

Để sử dụng oEmbed, ứng dụng của bạn phải trải qua quy trình Xét duyệt ứng dụng cho tính năng oEmbed Read.

Đối với trường nhập dữ liệu cung cấp URL mà chúng tôi có thể thử nghiệm oEmbed Read, hãy sử dụng điểm cuối Instagram oEmbed để lấy HTML nhúng cho mọi bài viết công khai trên trang Facebook hoặc trang Instagram chính thức của chúng tôi (hoặc lấy HTML nhúng cho chính một trong hai trang đó). Hãy thêm HTML nhúng được trả về vào trang của chính bạn - nơi bạn sẽ hiển thị nội dung oEmbed - rồi nhập URL của trang đó vào trường nhập dữ liệu.

Sau khi được phê duyệt tính năng oEmbed Read, bạn có thể nhúng trang, bài viết hoặc video của mình bằng các URL tương ứng.

Mã truy cập

Điểm cuối Instagram oEmbed yêu cầu Mã truy cập ứng dụng (khuyên dùng) hoặc Mã truy cập máy khách.

Mã truy cập ứng dụng

Nếu ứng dụng của bạn dựa vào máy chủ phụ trợ, bạn nên dùng Mã truy cập ứng dụng khi truy cập vào điểm cuối oEmbed. Giới hạn tốc độ phụ thuộc vào loại mã có trong yêu cầu và Giới hạn tốc độ mã ứng dụng cho phép tối đa 5 triệu yêu cầu mỗi ngày.

Bạn có thể xem hướng dẫn tạo Mã truy cập ứng dụng ở phần Mã ứng dụng trong tài liệu về Mã truy cập của chúng tôi.

Lưu ý rằng bạn tuyệt đối không nên dùng Mã truy cập ứng dụng bên phía máy khách. Các mã này phải luôn được bảo mật và lưu trữ trên máy chủ của bạn. Nếu ứng dụng của bạn phải dùng một mã bên phía máy khách, hãy dùng Mã truy cập máy khách.

Mã truy cập ứng dụng

Nếu ứng dụng của bạn phải truy cập vào điểm cuối oEmbed từ một tác nhân người dùng như thiết bị di động hoặc trình duyệt web, ứng dụng phải sử dụng Mã truy cập máy khách và sẽ phải tuân theo Giới hạn tốc độ mã máy khách.

Để lấy Mã truy cập máy khách, hãy đăng nhập vào Bảng điều khiển ứng dụng rồi chuyển đến phần Cài đặt > Nâng cao > Bảo mật > Mã ứng dụng.

Không giống như Mã truy cập ứng dụng, bạn không thể sử dụng riêng Mã truy cập máy khách trong yêu cầu điểm cuối oEmbed mà phải kết hợp với ID ứng dụng của bạn. Để thực hiện điều này, hãy thêm mã của bạn vào cuối ID ứng dụng, phân tách bằng dấu gạch đứng (|):

{app-id}|{client-token}

Ví dụ:

access_token=1234|5678

Giới hạn tốc độ

Giới hạn tốc độ phụ thuộc vào loại Mã truy cập mà ứng dụng của bạn đưa vào mỗi yêu cầu.

Giới hạn tốc độ mã ứng dụng

Các ứng dụng dựa vào Mã truy cập ứng dụng có thể tạo tối đa 5 triệu yêu cầu mỗi ngày.

Giới hạn tốc độ mã máy khách

Giới hạn tốc độ mã máy khách thấp hơn đáng kể so với Giới hạn tốc độ mã ứng dụng. Chúng tôi không tiết lộ giới hạn thực vì giới hạn này sẽ thay đổi tùy vào hoạt động trong ứng dụng của bạn. Tuy nhiên, bạn có thể yên tâm giả định rằng ứng dụng sẽ không đạt đến giới hạn trừ khi có hành vi giống như bot, chẳng hạn như nhóm hàng nghìn yêu cầu hoặc gửi hàng nghìn yêu cầu trên mỗi tác nhân/người dùng ứng dụng.

Lấy HTML nhúng

Để lấy HTML nhúng của bài viết trên Instagram, hãy gửi yêu cầu đến:

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

Hãy thay thế {url} bằng URL của bài viết trên Instagram mà bạn muốn truy vấn và thay {access-token} bằng Mã truy cập ứng dụng hay Mã truy cập máy khách (hoặc chuyển cho chúng tôi qua tiêu đề HTTP). Nếu bạn đang sử dụng Mã truy cập máy khách, hãy nhớ kết hợp mã này với ID ứng dụng bằng cách sử dụng dấu thẳng đứng, nếu không yêu cầu sẽ không thành công.

Khi thành công, API sẽ trả về đối tượng JSON chứa HTML nhúng của bài viết và dữ liệu bổ sung. HTML nhúng sẽ được chỉ định cho thuộc tính html.

Hãy xem tài liệu tham khảo về Instagram oEmbed để biết danh sách các thông số chuỗi truy vấn mà bạn có thể thêm để bổ sung cho yêu cầu. Bạn cũng có thể thêm thông số chuỗi truy vấn fields để chỉ định Trường mà bạn muốn nhận được. Nếu bạn bỏ qua, phản hồi sẽ bao gồm tất cả các Trường mặc định.

Yêu cầu mẫu

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

Phản hồi mẫu

Một số giá trị bị cắt bớt có dấu ba chấm (...) để dễ đọc.

{
  "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
}

Định dạng URL

Thông số chuỗi truy vấn url chấp nhận các định dạng URL sau:

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

Embed JS

HTML nhúng chứa thông tin tham chiếu đến thư viện JavaScript embed.js trên Instagram. Khi tải, thư viện này sẽ quét trang để tìm HTML của bài viết rồi tạo bài viết đó dưới dạng hiển thị đầy đủ. Nếu bạn muốn tải riêng thư viện, hãy đưa thông số chuỗi truy vấn omitscript=true vào yêu cầu của mình. Để khởi tạo HTML nhúng theo cách thủ công, hãy gọi hàm instgrm.Embeds.process() sau khi tải thư viện.

Kích thước bài viết

Bài viết được nhúng dễ thích ứng và sẽ điều chỉnh kích thước cho phù hợp với vùng chứa. Nghĩa là chiều cao sẽ thay đổi tùy vào chiều rộng của vùng chứa và độ dài của chú thích. Bạn có thể đặt chiều rộng tối đa bằng cách đưa thông số chuỗi truy vấn maxwidth vào yêu cầu của mình.

Lấy hình thu nhỏ

Bạn nên hiển thị tất cả HTML nhúng của bài viết bất cứ khi nào có thể. Nếu không thể làm vậy, bạn có thể lấy URL hình thu nhỏ của bài viết và hiển thị hình đó. Tuy nhiên, nếu làm vậy, bạn phải cung cấp thông tin ghi nhận rõ ràng bên cạnh hình ảnh, bao gồm thông tin ghi nhận tác giả ban đầu và Instagram, cũng như liên kết đến bài viết trên Instagram mà bạn đang truy vấn.

Để lấy URL hình thu nhỏ và thông tin ghi nhận của bài viết, hãy gửi yêu cầu đến:

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

Hãy thay thế {url} bằng URL của bài viết trên Instagram mà bạn muốn truy vấn, thay {maxwidth} bằng kích thước tối đa của hình thu nhỏ bạn muốn hiển thị và thay {access-token} bằng Mã truy cập ứng dụng hoặc Mã truy cập máy khách.

Yêu cầu mẫu

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..."

Phản hồi mẫu

Một số giá trị bị cắt bớt có dấu ba chấm (...) để dễ đọc.

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

Chuyển mã truy cập vào tiêu đề

Nếu không muốn thêm Mã truy cập vào chuỗi truy vấn của yêu cầu, bạn có thể chuyển mã này cho chúng tôi thông qua tiêu đề HTTP Authorization.

Authorization: Bearer {access-token}

Ví dụ:

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..."