Обзор

Instagram Basic Display API на базе HTTP можно использовать, чтобы передавать в приложения данные о профилях пользователей Instagram и опубликованных в их аккаунтах изображениях, видео и альбомах.

Компоненты

Базовые URL

• api.instagram.com — для получения маркеров доступа пользователей Instagram.
• graph.instagram.com — для получения медиафайлов и данных профилей пользователей Instagram.

Версии

Новый API использует ту же схему управления версиями и тот же цикл выпуска, что и Facebook Graph API. Новые версии выпускаются приблизительно каждые 3 месяца, и каждая из них поддерживается примерно 2 года, пока не будет упразднена.

Чтобы использовать в запросе определенную версию API, укажите ее номер в пути запроса после базового URL. Пример:

https://graph.instagram.com/v11.0/10218560180051171/media

Если не задать в запросе номер версии, по умолчанию будет использована версия, указанная на Панели приложений в разделе Настройки > Дополнительно > Обновить версию API.

Окно получения разрешений

Это окно позволяет приложению получать у пользователей коды авторизации и разрешения. Коды авторизации можно обменивать на маркеры доступа пользователей Instagram, которые необходимо указывать при запросе профилей пользователей приложения или их медиафайлов.

Информацию о том, как реализовать окно получения разрешений, см. в руководстве по получению маркеров доступа.

Коды авторизации

Эти коды можно обменивать на краткосрочные маркеры доступа пользователей Instagram. Чтобы получить код, реализуйте в приложении окно получения разрешений. Когда пользователь пройдет аутентификацию в этом окне и предоставит приложению все необходимые разрешения, мы перенаправим его в приложение вместе с кодом авторизации. Затем с помощью API можно обменять этот код на краткосрочный маркер доступа пользователя Instagram.

Коды авторизации действуют в течение 1 часа.

Маркеры доступа пользователей Instagram

Для аутентификации с помощью API используются маркеры доступа пользователей Instagram, работающие по протоколу OAuth 2.0. Эти маркеры действуют внутри приложения (т. е. уникальны для пары "приложение — пользователь") и могут быть краткосрочными или долгосрочными. Такие маркеры должны содержаться во всех запросах API для получения данных о пользователях Instagram и их медиафайлах.

Краткосрочные маркеры доступа

Краткосрочные маркеры доступа действуют в течение 1 часа, но их можно обменять на долгосрочные. Чтобы получать краткосрочные маркеры доступа, реализуйте в приложении окно получения разрешений. Когда пользователь пройдет аутентификацию в этом окне, мы перенаправим его обратно в приложение вместе с кодом авторизации, который можно обменять на краткосрочный маркер доступа.

Долгосрочные маркеры доступа

Краткосрочные маркеры доступа, срок действия которых не истек, можно обменять на долгосрочные, которые действуют в течение 60 дней. Долгосрочные маркеры можно обновлять до истечения срока их действия. Для этого необходимо отправить запрос к конечной точке GET /refresh_access_token.

Разрешения

Пользователи вашего приложения сами выбирают, какие их данные будут ему доступны. Для этого используются перечисленные ниже разрешения. Если пользователь не предоставит их в окне авторизации, приложение не сможет получить доступ к его данным.

• instagram_graph_user_profile — позволяет приложению считывать узел User (соответствует пользователю Instagram) и его границы контекста.
• instagram_graph_user_media — позволяет приложению считывать узел Media (соответствует изображению, видео или альбому) и его границы контекста.

Тестировщики Instagram могут предоставить эти разрешения вашему приложению в любой момент. Чтобы пользователи приложения, не имеющие роли в нем, могли предоставлять ему эти разрешения, для каждого из них в рамках проверки приложения должен быть предварительно одобрен расширенный доступ, а приложение должно находиться в рабочем режиме.

Разрешения, предоставляемые пользователями приложения с открытыми аккаунтами, действуют в течение 90 дней. Обновлениедолгосрочного маркера доступа пользователя приложения продлевает срок действия разрешения ещё на 90 дней (при условии, что предоставивший маркер пользователь имеет открытый аккаунт). Если у пользователя приложения закрытый аккаунт, продлить срок действия разрешения невозможно. Пользователь должен вновь предоставить его приложению.

Тестировщики Instagram

Чтобы разрешить пользователю Instagram тестировать ваше приложение, сначала нужно отправить приглашение соответствующему аккаунту (и пользователь должен принять его). Приглашение можно отправить из раздела Тестировщики Instagram (Панель приложений > Роли > вкладка Роли).

Чтобы принять приглашение, пользователю Instagram нужно войти в аккаунт, а затем выбрать (Значок профиля) > Редактировать профиль > Приложения и сайты > Приглашения тестировщиков на сайте или в мобильном приложении Instagram.

Ресурсы

Данные в API состоят из информации о пользователях Instagram и их медиафайлах (изображениях, видео, альбомах). Все данные защищены разрешениями. Чтобы ваше приложение получило доступ к определенной информации, пользователь должен предоставить ему соответствующее разрешение в окне авторизации.

Пользователи

Пользователям Instagram и их профилям соответствуют узлы User. Примечание. ID пользователей, которые использовались в устаревшем Instagram API, несовместимы с Instagram Basic Display API.

Медиафайлы

Фото, видео и альбомам соответствуют узлы Media (отдельные для каждого пользователя).

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

На все запросы к конечным точкам распространяется ограничение числа обращений платформы Graph API.

Текущее количество вызовов приложения можно проверить на вкладке Панель приложений > Instagram > Ограничение числа обращений Basic Display (сначала нужно добавить в приложение продукт Instagram).

Типы приложений

Бизнес-приложения не поддерживаются. Если у вас именно такое приложение, используйте Graph API для Instagram или создайте приложение другого типа.

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

Тестировщики Instagram могут предоставить вашему приложению разрешения Instagram в любой момент. Чтобы пользователи приложения, не имеющие роли в нем, могли предоставлять ему разрешения Instagram, для каждого из них в рамках проверки приложения должен быть предварительно одобрен расширенный доступ, а ваше приложение должно находиться в рабочем режиме.

Когда приложение будет закончено и готово к переводу в рабочий режим, ознакомьтесь с информацией о проверке приложений, примерами заявок и распространенными причинами их отклонения. Изучив эту процедуру, отправьте приложение на проверку, чтобы запросить одобрение разрешений для Instagram Basic Display API. Для этого выберите Панель приложений > Продукты > Instagram > Basic Display.

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

Подтверждение компании

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

Принцип работы

Чтобы использовать API, сначала нужно получить и представить пользователю приложения окно получения разрешений. Пользователь сможет пройти в нем аутентификацию и предоставить приложению разрешения на доступ к определенным данным. После аутентификации пользователь перенаправляется обратно в приложение. При этом передается код авторизации, который следует обменять на краткосрочный маркер доступа пользователя Instagram. Этот маркер можно использовать для запросов к конечным точкам User и Media, которые будут возвращать доступные вашему приложению данные, или для обмена на долгосрочный маркер.

Инструменты

Генератор маркеров пользователя

Генератор маркеров пользователя Instagram позволяет быстро генерировать долгосрочные маркеры доступа пользователя Instagram для любого из ваших общедоступных аккаунтов Instagram. Это полезно для тестирования приложения без окна авторизации или в тех случаях, когда вы используете скопированный код, предоставленный сторонним сервисом (например, для отображения своих данных Instagram на своем сайте).

Этот инструмент запускает окно получения разрешений, в котором можно выполнить вход от имени общедоступного аккаунта Instagram, указанного как аккаунт для тестирования. После входа инструмент сгенерирует долгосрочный маркер доступа, который можно скопировать и вставить. Примечание. Маркеры можно генерировать только для общедоступных аккаунтов Instagram.

Генератор маркеров можно найти здесь: Панель приложений > Продукты > Instagram > вкладка Basic Display.

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

Дальнейшие действия

Изучите руководство по началу работы. В нем рассказывается, как настраивать приложения и выполнять основные запросы через API.