13.3 Добавление API-соединений

Вызовы API процедур - это способ получения данных от внешних сервисов или запуска событий на стороне этих сервисов (отправка сообщения, списание денег с карты и т.д.). Обычно (но не всегда) первый тип вызовов осуществляется с помощью GET запросов, а второй с помощью POST. Для вызова обычно требуется аутентификация, чтобы сервис идентифицировал, кто вызывает процедуру (и мог брать оплату за каждый вызов и т.д.). Такие вызовы добавляются во вкладке API в Редакторе приложения . Здесь вы задаете аутентификацию для вызовов и тип использования вызовов, использовать как источник данных или же как действие.

Пример реализации вызовов API iTunes вы можете посмотреть здесь (!!!ЛНК!!!).

Реализация API-соединений может отличаться в зависимости от API. Так как большинство API следуют стандартам, при возникновении проблем мы рекомендуем обратится к сервису, предоставившему API или попросить помощи на форуме.

Аутентификация

Разработка вызовов начинается с метода аутентификации, которым будут подписаны вызовы во время работы. Аутентификация осуществляется несколькими стандартными способами. Обратите внимание, что при разработке API-соединения с использованием каких-либо ключей вам всегда нужно вводить актуальные ключи для теста. Эти ключи сохраняются только для работы над плагином. Они никогда не будут отправлены пользователям, которые используют плагин. Напротив, им нужно будет ввести свои собственные API-ключи в редакторе во вкладке Плагины.

Без аутентификации (No authentication)

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

Закрытый ключ в URL (Private key in URL)

Ключ добавляется в URL, имя ключа может быть изменено в редакторе.

Закрытый ключ в заголовке (Private key in header)

Ключ добавляется в заголовок всех запросов. Очень похож на предыдущий метод. Очень часто заголовок выглядит как: Authorization: KEY, но вы можете при необходимости изменить имя Authorization.

Базовая HTTP авторизация (HTTP Basic Auth)

В каждом запросе посылается пара логин/пароль, согласно базовому протоколу авторизации HTTP (см здесь (!!!ЛНк!!!).

Поток Oauth2 с паролем (Oauth2 Password Flow)

Пароль и имя пользователя используются для получения токена (подробности см здесь (!!!ЛНК!!!)), который имеет срок действия и может быть автоматически продлен вашим приложением. Данный токен возвращается при вызове точки входа, которую нужно заполнить в редакторе. Точку входа можно найти в документации к API. Для этого в документации выполните поиск по словам "token" или "OAuth Bearer token".

Специальный токен Oauth2 (Oauth2 Custom Token)

Данный поток подобен Потоку с паролем, но позволяет самостоятельно задать вызов, который возвращает токен, в том случае, если ваш подход отличается от стандартного, который описан выше. Токен будет добавлен к вызовам как Bearer Token (токен на предъявителя), и будет автоматически продлен при необходимости. Обратите внимание, что для корректного функционирования токен должен возвращаться в виде объекта как минимум с двумя ключами: access_token и expires_in .

Поток Oauth2 через User-Agent (Oauth2 User-Agent Flow)

Данный поток используется большинством сервисов, когда нужно связаться с API, работающим на стороне пользователя (Facebook, Pinterest, Google и т.д.). Это позволяет получить доступ к пользовательским данным при использовании API (таким как профиль пользователя на Facebook). Настойка этого происходит в несколько шагов, так как вам нужно пройти аутентификацию со своего собственного аккаунта, для того, чтобы иметь возможность делать аутентифицированные запросы в режиме редактирования и для инициализации вызовов.

Обычно начинают с настройки "приложения" в сервисе, с помощью которого вы собираетесь проходить аутентификацию. Этот сервис после настройки предоставит вам Client ID и Secret, с помощью которых ваше приложение будет связываться с сервисом.

Для начала вам нужно внести некоторую информацию и создать точки входа, которые нужны для получения токена и ID пользователя.Эта точка входа будет использоваться для генерации токена и подтверждения личности пользователя в сервисе. Вся эта информация есть в документации по API. Когда будете смотреть документацию, рекомендуем искать раздел не с SDK, а с использованием web/HTTP).

• Scope: каждый сервис, работающий по Oauth2 потребует от вас ввести параметр scope, который определяет уровень прав доступа, который вы запрашиваете у пользователей. Это может быть "только чтение"/"readonly", "запись"/"write", "отправка сообщений"/"send messages" ...

• Login Dialog redirect - это ссылка, по которой пользователь перейдет на сервис, чтобы авторизовать ваше приложение (и, возможно, сначала войдет в этот сервис). Часто она выглядит как: https://www.facebook.com/v2.8/dialog/oauth

• Access token endpoint - это ссылка, которая используется на сервере для получения токена доступа из временного кода. Для Facebook, это будет https://graph.facebook.com/v2.8/oauth/access_token

• User profile endpoint - это ссылка, которую вы используете уже будучи аутентифицированным для получения профиля текущего пользователя. В него обычно входит ID и email (кроме случаев, когда сервис не предоставляет email по API). Для Facebook, такая ссылка https://graph.facebook.com/v2.7/me ("me" - это общий шаблон) В некоторых случаях, если ID не возвращается в верхнем уровне ответа по предыдущей ссылке или ключ отличается от "id", вы можете переназначить ключ с помощью двух настроек после раздела с точкой входа.

Вот так выглядит аутентификация для Spotify:

В случае с Oauth2 User-Agent Flow, вам нужно аутентифицировать себя в вашем собственном аккаунте для того, чтобы инициализировать вызовы. Этот процесс можно пройти по соответствующей кнопке, после чего токен будет сохранен. Ваши личные и учетные данные в данном сервисе не будут разглашены пользователям вашего плагина.

Web токен JSON

Некоторые сервисы пользуются более продвинутым протоколом (!!!ЛНК!!!) для управления типами и правами доступа.Обычно это относится к сервисам корпоративного типа, например Box или Google Cloud. Для аутентификации через такие сервисы вам нужно ввести тип доступа, электронную почту, привязанную к учетной записи и точку входа, которая возвращает токен. Также вам нужен закрытый ключ RSA, которой предоставляется сервисом для установки соединения. Обратите внимание, что ключ должен находиться между "-----BEGIN RSA PRIVATE KEY-----" и

"-----END RSA PRIVATE KEY-----".

-----BEGIN RSA PRIVATE KEY-----
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
................................................................
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-----END RSA PRIVATE KEY-----

Общие заголовки

Если вам нужно добавить общие заголовки во все запросы, включая запросы аутентификации, вы можете задать их в данном разделе. Обратите внимание, что значения, которые вы здесь задаете могут быть типа "hidden"/"скрытые" или "secret"/"секретные". Скрытые настройки прописываются вами, как создателем плагина, вручную, и пользователи плагина не смогут задавать эти параметры. В большинстве случаев они используются для передачи технических заголовков типа content-type и т.д. Параметры секретного типа пользователям будет предложено задать во вкладке Плагины.

Задание точки входа для вызова

После ввода параметров аутентификации вы можете начать редактирование ваших вызовов. Начать нужно с определения метода запроса, потом скопировать адрес точки входа, на которую посылается запрос и задать параметры, которые должен заполнить пользователь. Обратите внимание, если вы введете часть URL между "[" и "]", значение в скобках будет параметром.

Параметры могут быть нескольких типов: публичные (public), скрытые (hidden) и секретные (secret).

• Публичные параметры будут изменяться пользователем на уровне вызова (например, для строкового параметра API вызова)

• Скрытые параметры используются создателем плагина и не будут раскрыты пользователю плагина. Например, в них может быть тип шифрования и т.д.

• Секретные параметры подходят для ключей и прочего. Пользователи будут вводить их в редакторе во вкладке Плагины.

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

JSON

Самый типовой случай использоваться REST API, возвращает объект парами ключ-значение. Если вы выберете этот тип, во всплывающем окне после инициализации вызова вам будет предложено выбрать типы данных для каждого ключа. Во время инициализации вызова Баббл сделает запрос и распознает данные, вернувшиеся в ответ.

XML

Некоторые API возвращают ответ в виде XML. Часто его можно конвертировать в объект JSON. Если вы работаете с таким API, то вы можете использовать XML и получать данные в виде JSON объекта, а затем действовать методом, описанным выше. Обратите внимание, что не все XML ответы могут быть конвертированы в JSON. Если у Баббл это не получится, выведется сообщение об ошибке.

Изображение

Некоторые API возвращают изображение в качестве ответа. Например, оно может быть в виде ссылки, которую можно использовать в тэге <img>. В таком случае API вызов в Bubble вернет изображение, которое может использоваться в элементе Изображение (Image) или в качестве фона страницы.

Текст, число

Вам нужно выбрать это тип, если API возвращает строку или число (без структурирования в JSON объект).

Обратите внимание, что, в случае с публичным API, смена типов может привести к несовместимости типов, поэтому вам следует быть осторожными, а также при публикации плагина описать в документации как возможное нарушение (см ниже).