Facebook oEmbed

Với điểm cuối Facebook oEmbed, bạn có thể lấy HTML nhúng và siêu dữ liệu cơ bản cho trang, bài viết và video để hiển thị trong một trang web hay ứng dụng khác.

Chúng tôi đã thay thế sản phẩm oEmbed bằng tính năng oEmbed Read. Nếu đã triển khai sản phẩm oEmbed trước ngày 08/06/2021, bạn sẽ phải hoàn thành quy trình Xét duyệt ứng dụng cho tính năng oEmbed Read trước ngày 07/09/2021. Nếu chưa được phê duyệt tính năng oEmbed Read trước ngày 07/09/2021, bạn sẽ không thể triển khai oEmbed.

Cách dùng phổ biến

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

Điểm cuối

Điểm cuối	Mô tả
`GET /oembed_page`	Lấy siêu dữ liệu cơ bản và HTML nhúng của trang Facebook.
`GET /oembed_post`	Lấy siêu dữ liệu cơ bản và HTML nhúng của bài viết trên Facebook.
`GET /oembed_video`	Lấy siêu dữ liệu cơ bản và HTML nhúng của video trên Facebook.

Yêu cầu

một tài khoản nhà phát triển trên Facebook
một ứng dụng trên Facebook ở chế độ Chính thức
một mã truy cập
Xét duyệt ứng dụng cho tính năng oEmbed Read

Giới hạn

Điểm cuối Facebook oEmbed chỉ dùng để nhúng nội dung trên Facebook vào trang web và ứng dụng. Không sử dụng các đ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 các điểm cuối 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.

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 Vui lòng 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 oEmbed để lấy HTML nhúng cho mọi bài biết hoặc video 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 Facebook 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 một trang, bài viết hoặc video, hãy gửi yêu cầu đến điểm cuối oEmbed của trang, bài viết hoặc video tương ứng:

Mục tiêu	Điểm cuối và cấu trúc của truy vấn
Trang	`GET /oembed_page?url={url}&access_token={access-token}`
Bài viết	`GET /oembed_post?url={url}&access_token={access-token}`
Video	`GET /oembed_video?url={url}&access_token={access-token}`

Thay thế {url} bằng URL của trang, bài viết hoặc video mà bạn muốn truy vấn và {access-token} bằng Mã truy cập ứng dụng hoặc Mã truy cập máy khách của bạn (hoặc chuyển cho chúng tôi qua tiêu đề HTTP). Nếu bạn 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 trang, bài viết hoặc video và dữ liệu bổ sung về trang, bài viết hoặc video đó. HTML nhúng sẽ được chỉ định cho thuộc tính html.

Hãy tham khảo tài liệu dành cho từng điểm cuối để biết danh sách các thông số chuỗi truy vấn mà bạn có thể thêm vào yêu cầu. Bạn cũng có thể thêm thông số chuỗi truy vấn fields vào bất kỳ yêu cầu nào để 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.

Ví dụ về yêu cầu trang

curl -i -X GET \
 "https://graph.facebook.com/v19.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC&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.

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

Định dạng URL

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

Trang

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

Bài viết

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}

Video

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

Theo mặc định, HTML nhúng chứa thông tin tham chiếu đến thư viện JavaScript sdk.js. Để lấy HTML nhúng mà không lấy thông tin tham chiếu nếu bạn muốn tải riêng HTML này, hãy thêm thông số chuỗi truy vấn omitscript=true.

Chuyển mã truy cập qua 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/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC" \
  --header "Authorization: Bearer 96481..."