Instagram oEmbed

Instagram oEmbedエンドポイントにクエリを行い、Instagram投稿の埋め込みHTMLと基本メタデータを取得して、他のウェブサイトやアプリで投稿を表示します。写真、動画、リール、ガイド投稿をサポートしています。

一般的な用途

メッセージアプリに投稿をレンダリングする。
ウェブサイトやブログに投稿を埋め込む。
コンテンツ管理システムに投稿をレンダリングする。

エンドポイント

エンドポイント	説明
`GET /instagram_oembed`	Instagram投稿の埋め込みHTMLと基本メタデータを取得します。

要件

制限

Instagram oEmbedエンドポイントは、Instagramコンテンツをウェブサイトやアプリに埋め込むために使用することだけを意図しています。他のいかなる目的にも使用しないでください。エンドポイントのメタデータとページ、投稿、動画コンテンツ(またはその派生物)を、ページ、投稿、動画のフロントエンドビューを提供する以外の目的で使用することは固く禁じられています。この禁止規定は、メタデータとコンテンツの使用、操作、抽出、または保持を対象にしています。分析目的でメタデータからのページ、投稿、動画に関する情報の派生が含まれますが、これらに限定されるものではありません。
非公開、アクティブでない、または年齢制限されているInstagramアカウントでの投稿はサポートされていません。
埋め込みが無効になっているアカウントはサポートされていません。
ストーリーズはサポートされていません。
Shadow DOMはサポートされていません。

アプリレビュー

oEmbedを使うには、アプリがoEmbed読み取り機能についてアプリレビューを受ける必要があります。

フィールドからOembed読み取りをテストできるURLを提供するには、Instagram oEmbedエンドポイントを使用して公式FacebookページまたはInstagramページで何らかの公開投稿の埋め込みHTMLを取得します(またはそれぞれのページそのものの埋め込みHTMLを取得します)。返された埋め込みHTMLを、oEmbedコンテンツを表示するページに追加し、そのページのURLをフォームフィールドに入力します。

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

アクセストークン

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

アプリアクセストークン

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

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

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

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

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

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

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

{app-id}|{client-token}

以下はその例です。

access_token=1234|5678

レート制限

レート制限は、各リクエストにアプリが含めるアクセストークンの種類に依存します。

アプリトークンレート制限

アプリアクセストークンを使用するアプリでは、24時間当たり500万リクエストまで行えます。

クライアントトークンレート制限

クライアントトークンレート制限は、アプリトークンレート制限に比べて大幅に低くなります。制限はアプリのアクティビティに応じて変化するため、具体的な制限は提示しません。しかし、アプリがボットのような挙動(何千というリクエストを一括で行う、または単一のエージェントかアプリユーザーが何千ものリクエストを送信する)を行わない限り、制限に達することはないと考えて差し支えありません。

埋め込みHTMLの取得

Intagram投稿の埋め込みHTMLを取得するには、次のようにリクエストを送信します。

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

{url}をクエリ対象となるInstagram投稿のURLに置き換え、{access-token}をアプリアクセストークンかクライアントアクセストークンに置き換えます(またはHTTPヘッダー経由でアクセストークンを渡します)。クライアントアクセストークンを使用する場合は、必ずパイプ記号を使ってアプリIDと組み合わせてください。そうしないと、リクエストは失敗します。

成功すると、APIは、投稿の埋め込みHTMLおよびその他のデータを含むJSONオブジェクトを返します。埋め込み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フォーマット

urlクエリ文字列パラメーターは、次の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をレンダリングすることをおすすめします。これを行えない場合は、投稿のサムネイル画像URLを取得して、そのURLを代わりにレンダリングすることができます。ただしその場合は、画像の横にオリジナルの著者およびInstagramへのアトリビューションと、クエリの対象であるInstagram投稿へのリンクを含む、明確なアトリビューションを提供する必要があります。

投稿のサムネイルURLとアトリビューション情報を取得するには、次のリクエストを送信します。

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

{url}はクエリ対象となるInstagram投稿のURLに置き換え、{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..."