ソーシャルプラグイン

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読み取りをテストできるURLを提供するには、oEmbedエンドポイントを使用して公式FacebookページまたはInstagramページでいずれかの公開投稿または動画の埋め込みHTMLを取得します(またはそれぞれのページそのものの埋め込みHTMLを取得します)。返された埋め込みHTMLをoEmbedコンテンツを表示する自分自身のページに追加し、そのページのURLをフォームフィールドに入力します。

oEmbed読み取り機能の承認が完了すると、ページ、投稿、または動画を、それぞれのURLを使用して埋め込むことができます。

アクセストークン

Facebook oEmbedエンドポイントは、アプリアクセストークン(推奨)またはクライアントアクセストークンのいずれかを必要とします。

アプリアクセストークン

アプリがバックエンドサーバーを使用している場合、oEmbedエンドポイントにアクセスする際にはアプリアクセストークンを使用することをおすすめします。レート制限は、リクエストに含まれるトークンの種類によって異なりますが、アプリトークンレート制限では1日に500万リクエストまで許可されます。

アプリアクセストークンの生成方法は、Facebookのアクセストークンドキュメントのアプリトークンのセクションをご覧ください。

アプリアクセストークンは絶対にクライアントサイドで使用しないでください。トークンは常にサーバーで安全に保管しなければなりません。アプリがクライアントサイドでトークンを使用する必要がある場合は、代わりにクライアントアクセストークンを使用してください。

クライアントアクセストークン

ユーザーエージェント(モバイルデバイスやウェブブラウザーなど)からoEmbedエンドポイントにアクセスするアプリは、クライアントアクセストークンを使用する必要があり、クライアントトークンレート制限の対象になります。

クライアントアクセストークンを取得するには、アプリダッシュボードにログインし、[設定] > [詳細設定] > [セキュリティ] > [クライアントトークン]の順にアクセスします。

クライアントアクセストークンは、アプリアクセストークンとは異なり、単独でoEmbedエンドポイントリクエストに使用することはできず、アプリIDと組み合わせて使用する必要があります。これを行うには、トークンをパイプ記号(|)で区切ってアプリIDの末尾に追加します:

{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}を、クエリを行うページ、投稿、または動画のURLに置き換え、{access-token}をアプリまたはクライアントアクセストークンに置き換えます(またはHTTPヘッダーで渡します)。クライアントアクセストークンを使用する場合は、必ずパイプ記号を使ってアプリIDと組み合わせてください。そうしないと、リクエストは失敗します。

成功すると、APIはJSONオブジェクトを返します。この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フォーマット

urlクエリ文字列パラメーターは、次の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..."