oEmbed для Instagram

Конечную точку oEmbed для Instagram можно запросить, чтобы получить HTML-код для встраивания и базовые метаданные публикации Instagram для ее отображения на другом сайте или в приложении. Поддерживаются фото- и видеопубликации, видео Reels и путеводители.

Стандартное использование

Отображение публикаций в приложениях для обмена сообщениями.
Встраивание публикаций на сайты и в блоги.
Отображение публикаций в системах управления контентом.

Конечные точки

Конечная точка	Описание
`GET /instagram_oembed`	Получение базовых метаданных и HTML-кода для встраивания публикации Instagram.

Требования

Аккаунт разработчика Facebook.
Приложение Facebook в рабочем режиме.
Маркер доступа.
Проверка приложения для функции oEmbed Read.

Ограничения

Конечная точка oEmbed для Instagram предназначена только для встраивания контента Instagram на сайты и в приложения. Использовать ее в любых других целях запрещено. Строго запрещается использовать метаданные и контент страниц, публикаций или видео и их производные, полученные с помощью этой конечной точки, в любых целях, кроме отображения этих страниц, публикаций или видео в пользовательском интерфейсе. Этот запрет распространяется на потребление, изменение, извлечение и хранение метаданных и контента, включая получение из метаданных информации о страницах, публикациях и видео в целях анализа.
Публикации конфиденциальных и неактивных аккаунтов Instagram, а также аккаунтов с ограничением по возрасту не поддерживаются.
Аккаунты, которые отключили встраивание, не поддерживаются.
Истории не поддерживаются.
Shadow DOM не поддерживается.

Проверка приложения

Чтобы использовать oEmbed, ваше приложение должно пройти проверку для функции oEmbed Read.

Для поля формы URL для тестирования oEmbed Read укажите конечную точку oEmbed для Instagram, чтобы получить HTML-код встраивания для любой общедоступной публикации на нашей официальной Странице Facebook или странице Instagram (или получите HTML-код для встраивания на любой из этих страниц). Добавьте полученный HTML-код встраивания на собственную страницу, где будет отображаться контент oEmbed, и введите URL этой страницы в поле формы.

Получив одобрение на использование функции oEmbed Read, вы сможете встраивать собственные страницы, публикации и видео с помощью соответствующих URL.

Маркеры доступа

Для конечной точки oEmbed для Instagram требуется маркер доступа приложения (рекомендуется) или маркер доступа клиента.

Маркеры доступа приложения

Если ваше приложение работает на сервере, для доступа к конечной точке oEmbed рекомендуется использовать маркер доступа приложения. Ограничения числа обращений зависят от типа маркера доступа, указанного в запросе. Ограничение для маркера доступа приложения составляет 5 миллионов запросов в день.

Инструкции по генерации маркера доступа приложения можно найти здесь.

Обратите внимание: маркеры доступа приложения не следует использовать на стороне клиента. Они должны храниться в безопасности на вашем сервере. Если вашему приложению необходим маркер доступа на стороне клиента, используйте маркер доступа клиента.

Маркеры доступа клиента

Если вашему приложению нужно обращаться к конечной точке oEmbed из пользовательского агента, например с мобильного устройства или из браузера, используйте маркер доступа клиента. В таком случае для него будут действовать соответствующие ограничения числа обращений.

Чтобы получить маркер доступа клиента, войдите в панель приложений и перейдите в раздел Настройки > Расширенные > Безопасность > Маркер клиента.

В отличие от маркеров доступа приложения, маркеры доступа клиента нельзя использовать в запросах к конечной точке oEmbed самостоятельно: к ним всегда нужно добавлять ID вашего приложения. Для этого добавьте маркер доступа в конце ID приложения, отделив его вертикальной чертой (|):

{app-id}|{client-token}

Пример:

access_token=1234|5678

Ограничения числа обращений

Ограничения числа обращений зависят от типа маркера доступа, который приложение указывает в каждом запросе.

Ограничения числа обращений для маркера приложения

Приложения, использующие маркер доступа приложения, могут выполнять до 5 миллионов запросов каждые 24 часа.

Ограничения числа обращений для маркера клиента

Ограничения числа обращений для маркера клиента значительно ниже ограничений для маркера приложения. Указать точное ограничение невозможно, так как оно изменяется в зависимости от активности приложения. В большинстве случаев ваше приложение не достигнет ограничения, если оно не ведет себя как бот (в частности, не отправляет тысячи запросов в одном пакете или тысячи запросов на каждый агент либо каждого пользователя).

Получение HTML-кода для встраивания

Чтобы получить HTML-код для встраивания публикации Instagram, отправьте такой запрос:

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

Замените {url} на URL публикации Instagram, которую вы хотите запросить, а {access-token} — на маркер доступа приложения или клиента (или передайте его нам в заголовке HTTP). Если вы используете маркер доступа клиента, не забудьте добавить к нему ID приложения, отделив вертикальной чертой.

В случае успеха API вернет объект JSON, содержащий HTML-код публикации для встраивания, а также дополнительные данные. HTML-код встраивания содержится в свойстве html.

Список параметров, которые можно включать в строку запроса, см. в справке по конечной точке oEmbed для Instagram. Можно также добавить параметр 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}

Библиотека JavaScript для встраивания

HTML-код для встраивания содержит ссылку на библиотеку JavaScript embed.js для Instagram. При загрузке библиотека проверяет страницу на предмет HTML-кода публикации и генерирует полностью отображаемую публикацию. Чтобы загрузить библиотеку отдельно, добавьте в запрос параметр omitscript=true. Чтобы инициализировать HTML-код встраивания вручную, вызовите функцию instgrm.Embeds.process() после загрузки библиотеки.

Размер публикации

Встраиваемая публикация адаптируется под размер ее контейнера. Это означает, что высота публикации изменяется в зависимости от ширины контейнера и длины подписи. Чтобы указать максимальную ширину, добавьте в запрос параметр maxwidth.

Получение миниатюр

Рекомендуем по возможности отображать HTML-код публикации целиком. Если это не удается сделать, можно получить URL изображения миниатюры публикации и отображать ее. В этом случае необходимо указать информацию об авторских правах: имя автора, ссылку на исходную публикацию и на Instagram.

Чтобы получить URL миниатюры и информацию об авторских правах, отправьте такой запрос:

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

Замените {url} на 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/"
}

Передача маркеров доступа в заголовке

Если вы не хотите указывать маркер доступа в строке запроса, его можно передать в HTTP-заголовке Authorization.

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