Перейти к основному содержимому

Вызовы API

На этой странице вы узнаете базовые сведения о различных концепциях добавления вызова API в ваш проект. Они являются строительными блоками для добавления вызова API. В зависимости от определения API вы можете использовать некоторые или все эти концепции, чтобы успешно реализовать вызов API в вашем проекте.

Вот они:

Заголовки​

Заголовки обычно содержат метаданные, связанные с HTTP-запросом или ответом вызова API. HTTP-заголовки в основном делятся на две категории:

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

Передача заголовков запроса​

Некоторые распространенные заголовки запроса, которые могут потребоваться при отправке запроса:

  • Authorization: Используется для аутентификации запроса.
  • Content-Type: Используется при отправке POST/PUT/PATCH-запроса, содержащего тело сообщения.

Чтобы передать заголовок запроса:

  1. Выберите вкладку Headers и нажмите кнопку + Add Header.
  2. В поле ввода введите имя заголовка, за которым следует двоеточие (:), и его значение (например, Content-Type: application/json).

к сведению

По умолчанию для любого HTTP POST-запроса Content-Type равен application/json, поэтому если тело данных в формате JSON, вы можете пропустить определение Content-Type.

Передача токена аутентификации (как заголовок запроса)​

Возможно, вам потребуется добавить защищенный API. Это означает, что он возвращает результаты только в том случае, если вы передадите токен авторизации (он же auth token) в параметре заголовка. Обычно это делается для предотвращения злоупотреблений. Давайте разберем, как добавить токен аутентификации.

Передача статического токена аутентификации​

Некоторые сервисы предоставляют статический токен аутентификации. Такой токен не меняется, пока вы вручную не сгенерируете новый.

Чтобы передать статический токен аутентификации:

  1. Выберите вкладку Headers и нажмите кнопку + Add Header.
  2. В поле ввода введите имя заголовка как Authorization, за которым следует двоеточие (:), и его значение (например, Authorization: Bearer YOUR_TOKEN).

Передача динамического токена аутентификации​

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

Как сохранить токен аутентификации?

После успешного выполнения вызова входа убедитесь, что вы сохранили токен аутентификации в переменной состояния приложения (с Persisted -> True). Посмотрите визуалы ниже:

api-token-variable.png

Теперь вы можете передать динамический токен:

  1. Выберите вкладку Headers и нажмите кнопку + Add Header.
  2. В поле ввода введите имя заголовка как Authorization, за которым следует двоеточие (:), а затем введите любое имя переменной в квадратных скобках (например, Authorization: Bearer [auth_token]).
  3. Выберите вкладку Variables и создайте новую переменную с тем же именем, которое вы указали в скобках. Это будет использоваться для передачи значения токена из переменной состояния приложения в вызов API.

Теперь из вызова API (который требует токена аутентификации) передайте значение токена из переменной состояния приложения.

Получение заголовков ответа​

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

Чтобы получить заголовок ответа:

  1. Убедитесь, что вы добавили действие вызова API и указали Action Output Variable Name.
  2. Теперь, когда/где Value Source установлен в From Variable, выберите Action Outputs > [Action Output Variable Name] (например, Action Outputs > loginResponse).
  3. Установите API Response Options в Get Response Header.
  4. Введите Header Name. Обратите внимание, что это должно совпадать с именем заголовка ответа из вашего вызова API.
  5. Нажмите Confirm.

Параметры запроса​

Это необязательные параметры, которые вы можете передать с вызовом API; они помогают форматировать данные ответа, возвращаемые сервером. Обычно они добавляются в конец URL с вопросительным знаком (?) в качестве разделителя и представлены как пары ключ-значение.

Пример URL с параметрами запроса выглядит так (NASA Open API):

https://api.nasa.gov/neo/rest/v1/feed?start_date=2015-09-07&end_date=2015-09-08&api_key=DEMO_KEY

Здесь start_date, end_date и api_key — это параметры запроса, переданные для получения конкретных данных.

Вот еще один пример: этот вызов API <https://www.breakingbadapi.com/api/characters?limit=20&offset=0> имеет два параметра запроса. Параметр limit указывает на загрузку 20 элементов на страницу, а offset — на количество элементов для пропуска. Это называется пагинацией на основе смещения.

Передача параметров запроса​

Чтобы передать параметры запроса для GET или DELETE вызова API:

  1. Выберите вкладку Query Parameters и нажмите кнопку + Add Query Parameter.
  2. Введите Name параметра запроса.
  3. Установите Value Source в Specific Value или From Variable.
    1. Если вы хотите передать это значение с вашей страницы, переменной состояния приложения или любого другого источника (т. е. динамическое значение), выберите From Variable, а затем из выпадающего списка Select Variable выберите уже созданную переменную (см., как создать переменную), или нажмите + Create New Variable. Примечание: Это немедленно создаст новую переменную с тем же именем, что и параметр запроса. Однако вам все равно нужно открыть вкладку Variables и установить ее Type.
    2. Если вы хотите передать статическое/фиксированное значение, выберите Specific Value, установите Type и введите Value.

Ниже приведен пример передачи параметра запроса для URL -> https://api.instantwebtools.net/v2/passenger?page=10&size=20

В редких случаях вы можете захотеть передать параметры запроса для других методов вызовов API, таких как POST, PUT и PATCH. Для этого:

  1. В URL вашего API замените жестко заданные значения на значимое имя в скобках (например, с https://api.instantwebtools.net/v2/passenger?``**page=0** на https://api.instantwebtools.net/v2/passenger?``**page=[page]**).
  2. Выберите вкладку Variables и создайте новую переменную с тем же именем, которое вы указали в скобках.

Переменные​

Переменные позволяют передавать динамические значения из любой части вашего приложения в вызовы API. Вот когда они бывают полезны:

  • Отправка токена аутентификации из состояния вашего приложения в заголовок запроса вызова API.
  • Использование имени пользователя и пароля из виджетов TextField в теле запроса вызова API.
  • Включение выбранных дат в качестве параметров запроса.
  • Изменение базового URL на динамический URL.

Создание переменных​

Чтобы создать переменные, выберите вкладку Variables, введите ее Name, выберите подходящий Type и укажите Default Value, если хотите.

variables.png

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

Вот как вы можете использовать переменную для создания динамического базового URL:

dynamic-base-url.png

Тело​

Вы можете отправлять данные (как тело запроса) при вызове API методов POST, PUT или PATCH, определяя их внутри Body. Самый распространенный тип — формат JSON, который является самым простым способом передачи данных в теле запроса.

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

Здесь вы увидите создание тела запроса в следующих форматах:

Формат JSON​

Чтобы создать тело запроса в формате JSON:

  1. Сначала, если вы еще не сделали этого, создайте переменные (например, переменные username и password, которые потребуются для передачи значений с страницы входа в вызов API входа).
  2. Выберите вкладку Body и установите выпадающий список Body в JSON.
  3. Скопируйте и вставьте тело запроса и замените значения на переменные, перетаскивая их в тело JSON.

Текстовый формат​

Этот формат используется для отправки текстовых данных в теле запроса API. Например, в SOAP API тело запроса обычно в текстовом формате и содержит XML-данные.

Чтобы создать тело запроса в текстовом формате:

  1. Сначала, если вы еще не сделали этого, создайте переменные.
  2. Выберите вкладку Body и установите выпадающий список Body в Text.
  3. Скопируйте и вставьте тело запроса и замените значения на переменные, перетаскивая их в тело запроса.

Формат x-www-form-urlencoded​

Чтобы создать тело запроса в формате x-www-form-urlencoded:

  1. Сначала, если вы еще не сделали этого, создайте переменные (например, переменные username и password, которые потребуются для передачи значений с страницы входа в вызов API входа).
  2. Выберите вкладку Body и установите выпадающий список Body в x-www-form-urlencoded.
  3. Нажмите + Add Parameter и введите Name параметра.
  4. Установите Value Source в Specific Value или From Variable.
    1. Если вы хотите передать это значение с вашей страницы, переменной состояния приложения или из любого другого источника (т. е. динамическое значение), выберите From Variable, а затем из выпадающего списка Select Variable выберите уже созданную переменную (см., как создать переменную), или нажмите + Create New Variable. Примечание: Это немедленно создаст новую переменную с тем же именем, что и параметр. Однако вам все равно нужно открыть вкладку Variables и установить ее Type.
    2. Если вы хотите передать статическое/фиксированное значение, выберите Specific Value, установите Type и введите Value.

Формат Multipart​

Тело запроса multipart — это формат данных, используемый в HTTP-запросах, который позволяет передавать несколько частей данных в одном запросе. Он обычно используется для загрузки файлов.

Чтобы создать тело запроса в формате multipart:

  1. Выберите вкладку Body и установите выпадающий список Body в Multipart.
  2. Нажмите + Add Parameter и введите Name параметра.
  3. Установите Value Source в From Variable, а затем из выпадающего списка Select Variable нажмите + Create New Variable. Примечание: Это немедленно создаст новую переменную с тем же именем, что и параметр.
  4. Теперь перейдите на вкладку Variables и установите Type в Uploaded File. Это позволит вам передавать файл, хранящийся локально на устройстве, с помощью действия, такого как Upload/Save Media.

Ответ API (JSON) в/из типа данных​

Преобразование между ответом API (JSON) и типами данных часто называется десериализацией и сериализацией JSON. Это позволяет преобразовывать JSON-данные из ответа API в Custom Data Type, когда вы их получаете. Также это позволяет преобразовывать ваш Custom Data Type обратно в JSON при отправке данных в запросе API.

к сведению

Это более надежный и удобный в обслуживании способ работы с JSON-данными в вашем приложении. Он снижает сложность и потенциальные ошибки (например, опечатки) по сравнению с ручным навигацией по путям JSON.

Создание пользовательского типа данных, соответствующего структуре JSON​

Сначала создайте тип данных с той же структурой, что и ответ API. Вот как выглядит пример JSON-ответа после его отображения в Custom Data Type.

custom-data-type-json-response.png

Создание пользовательского типа данных в соответствии с JSON-ответом

После этого вы можете выбрать преобразование в или из тип данных в зависимости от ваших требований.

JSON в тип данных​

Давайте разберем, как получить JSON в Custom Data Type, используя пример, который извлекает список продуктов из этого API. Вот как это выглядит:

img.png

Вот как это сделать:

  1. Сначала убедитесь, что вы создали пользовательский тип данных, который соответствует структуре вашего JSON.
  2. Откройте определение вызова API > Response & Test tab > Response Type > включите Parse as Data Type. Выберите Data Type, в который вы хотите преобразовать. В этом примере это 'AllProducts'.

img_1.png

  1. На ListView после добавления запроса backend вызова API получите значения, установив следующие параметры.

    1. Generate Children from Variable, установив API Response Options в As Data Type.
    2. Установите Available Options в Data Structure Field, поскольку мы хотим захватить только конкретное поле, которое содержит список продуктов, а не другие элементы, такие как 'total' и 'skip'.
    3. Select Field в поле, которое содержит список продуктов, т. е. 'products' в этом примере.
    4. Нажмите Confirm дважды.

  1. Теперь вы можете привязывать данные в элементах UI так, как обычно, установив Available Options в Data Structure Field и Select Field, который вы хотите отобразить.

JSON из типа данных​

Иногда вы можете захотеть динамически создать тело JSON и передать его вместе с запросом API вместо ручной настройки каждого поля в редакторе вызова API. Вы можете сделать это, добавив данные в Custom Data Type, а затем преобразовав его в JSON при выполнении вызова API.

Давайте разберем пример добавления продукта, отправив его данные в формате JSON в запросе API.

add-product.png

Вот как это сделать:

  1. Сначала создайте пользовательский тип данных, который соответствует формату JSON тела запроса API. Вот как это выглядит в этом примере.

img_2.png

  1. В вашем вызове API создайте переменную с типом JSON и поместите ее в раздел Body.

  1. При нажатии кнопки Add мы сохраним значения из UI в переменную состояния страницы пользовательского типа данных. Затем, при выполнении вызова API, передадим эту переменную состояния страницы и установим Available Options в To JSON.

Путь JSON​

JSONPath — это язык запросов для JSON. Используя путь JSON, вы можете извлекать конкретные данные из всего JSON-ответа.

примечание

Обычно вы получаете ответ в формате JSON от запроса API.

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

Некоторые примеры выражений JSONPath следующие:

  • $.data.name
  • $.users[0].name
  • $.users[:].name

Ведущий $ представляет корневой объект, точка (.) используется для доступа к ключам внутри JSON, значение в скобках ([0]) представляет индекс массива, если ключ содержит массив, а ([:]) выберет все объекты внутри списка.

Давайте разберем реальные примеры пути JSON для следующего ответа API:

{
  "page": 1,
  "per_page": 6,
  "total": 3,
  "total_pages": 2,
  "data": [
    {
      "id": 1,
      "email": "george.bluth@reqres.in",
      "first_name": "George",
      "last_name": "Bluth",
      "avatar": "https://reqres.in/img/faces/1-image.jpg"
    },
    {
      "id": 2,
      "email": "janet.weaver@reqres.in",
      "first_name": "Janet",
      "last_name": "Weaver",
      "avatar": "https://reqres.in/img/faces/2-image.jpg"
    },
    {
      "id": 3,
      "email": "emma.wong@reqres.in",
      "first_name": "Emma",
      "last_name": "Wong",
      "avatar": "https://reqres.in/img/faces/3-image.jpg"
    }
  ],
  "support": {
    "url": "https://reqres.in/#support-heading",
    "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
  }
}
$.total

Это вернет следующие данные:

3

$.data

Это вернет следующие данные:

[
   {
      "id": 1,
      "email": "george.bluth@reqres.in",
      "first_name": "George",
      "last_name": "Bluth",
      "avatar": "https://reqres.in/img/faces/1-image.jpg"
   },
   {
      "id": 2,
      "email": "janet.weaver@reqres.in",
      "first_name": "Janet",
      "last_name": "Weaver",
      "avatar": "https://reqres.in/img/faces/2-image.jpg"
   },
   {
      "id": 3,
      "email": "emma.wong@reqres.in",
      "first_name": "Emma",
      "last_name": "Wong",
      "avatar": "https://reqres.in/img/faces/3-image.jpg"
   }
]

$.data[0]

Это вернет объект по индексу 0 (т. е. первый объект).

{
   "id": 1,
   "email": "george.bluth@reqres.in",
   "first_name": "George",
   "last_name": "Bluth",
   "avatar": "https://reqres.in/img/faces/1-image.jpg"
}

$.data[0].email

Это вернет значение email объекта по индексу 0.

"george.bluth@reqres.in"

$.data[:].email

Это вернет email всех объектов внутри data.

[
  "george.bluth@reqres.in",
  "janet.weaver@reqres.in",
  "emma.wong@reqres.in"
]

Важно

Ключи JSON должны начинаться с буквы, подчеркивания или знака доллара. Они не могут начинаться с числового символа. Однако в случаях, когда у вас есть ключи с числовыми префиксами, такие как $.0_image, вы можете получить к ним доступ с помощью нотации скобок, как это: $.["0_image"].

к сведению

Узнайте больше о JSONPath и как определить правильное выражение.

Добавление предопределенного пути JSON​

Вы можете легко определять и управлять JSON Paths для ваших вызовов API в FlutterFlow, чтобы парсить и извлекать необходимые данные. После добавления вы можете использовать их как Predefined Path при доступе к JSON Body.

Сначала создайте и протестируйте ваш вызов API. В разделе JSON Paths нажмите + Add JSON Path, введите ваш JSON Path и присвойте ему имя. Если выражение валидно, под Response Preview появится предварительный просмотр ответа. Нажмите иконку Preview, чтобы увидеть полный ответ. Если ответ содержит список элементов, опция Is List будет включена автоматически.

В разделе Recommended вы найдете предложенные пути JSON, которые могут содержать необходимые данные.

Использование пути JSON​

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

Чтобы использовать предопределенный путь JSON, сначала выберите ответ API. Затем установите API Response Options в JSON Body, а Available Options — в JSON Path или Predefined Path. Наконец, укажите имя пути JSON или выберите из предопределенного пути JSON, чтобы отобразить извлеченные данные для использования в вашем приложении.

Расширенные настройки​

Вы можете сделать вызов API приватным и изменить настройки прокси с помощью расширенных настроек.

Приватные вызовы API​

Сделать вызов API приватным полезно, если он использует токены или секреты, которые вы не хотите раскрывать в вашем приложении. Включение этой настройки направит этот вызов API безопасно через Firebase Cloud Functions.

private-cloud-func.png

Чтобы сделать вызов API приватным, откройте вкладку Advanced Settings, включите переключатель Make Private, нажмите Save, а затем Deploy APIs.

Опционально, вы можете заставить пользователя аутентифицироваться через Firebase authentication для выполнения этого вызова API. Для этого включите переключатель Require Authentication.

Приватные API развертываются как Cloud Functions в вашем проекте Firebase. При развертывании вы можете настроить следующие параметры:

  • Use Custom Name for Cloud Function: При включении позволяет указать пользовательское имя для развернутой Cloud Function. По умолчанию эта опция отключена, и Cloud Function называется ffPrivateApiCall.
  • Private API Cloud Function Instances: Вы можете настроить количество экземпляров Cloud Function для оптимизации производительности и управления затратами.
    • Min Instances: Установите минимальное количество активных экземпляров, чтобы уменьшить задержку и избежать холодных запусков. Установка этого значения больше 0 сохранит экземпляры теплыми, но может повлечь дополнительные затраты.
    • Max Instances: Определите максимальное количество экземпляров, которые могут масштабироваться в зависимости от спроса.
    Note: Чтобы минимизировать затраты, вы можете установить значение Min Instances в 0. Для подробной информации о ценах обратитесь на страницу Cloud Functions Pricing.
примечание
  • Если вы сделаете вызов API приватным, Firebase должен быть подключен к вашему проекту. Следуйте инструкциям на этой странице для интеграции Firebase с FlutterFlow.
  • Если вы включите переключатель Require Authentication, Firebase Authentication должен быть правильно настроен. Посмотрите эту страницу для настройки аутентификации.

Обработка потокового ответа​

При работе с API, которые отправляют данные непрерывно, такими как Server Sent Events (SSE), вы можете включить эту опцию. Это гарантирует, что ваше приложение сможет обрабатывать непрерывный поток данных по долгоживущему HTTP-соединению для отображения обновлений в реальном времени.

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

к сведению

Обычно вы можете определить, поддерживает ли API потоковую передачу, проверив его документацию. Ищите ключевые слова вроде "event stream" или "processing chunks".

Подробнее

Узнайте больше о добавлении и использовании Streaming APIs.

Изменение настроек прокси​

По умолчанию, когда вы тестируете вызовы API внутри нашего конструктора, в режиме Run и Test, мы используем прокси для маршрутизации ваших вызовов, чтобы избежать проблемы CORS. Однако, если вы хотите использовать свой прокси, вы можете отключить эти настройки и указать URL вашего прокси.

Чтобы отключить текущие настройки прокси и указать URL вашего прокси:

  1. Откройте вкладку Advanced Settings.
  2. Отключите Use Proxy for Test и/или Use Proxy for Run/Test Mode.
  3. Включите Use Custom Proxy URL.
  4. Введите Proxy Prefix URL (например, https://your-proxy-server.com).

proxy-settings.png

Кэширование результатов API​

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

Декодирование ответов как UTF-8​

Включение этой опции гарантирует, что данные, полученные с сервера или сайта, читаются как UTF-8 — распространенный способ хранения текста. Обычно сервер или сайт указывает, как читать его данные, но иногда этого не происходит. Эта опция гарантирует, что данные читаются в формате UTF-8, даже если сайт не указывает это.

Перехватчики API​

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

Он действует как посредник между вашим приложением и сервером API. Таким образом, когда вы выполняете вызов API из вашего приложения, запрос сначала проходит через перехватчик. Перехватчик может затем проверить запрос, внести в него изменения (например, добавить заголовки или изменить URL) и даже отменить запрос, если это необходимо. Аналогично, когда сервер отвечает на ваш запрос, ответ проходит через перехватчик перед достижением вашего приложения.

Давайте разберем, как добавить перехватчик:

  1. Перейдите на вкладку Advanced Settings.
  2. Нажмите + Add Interceptors и выберите + Create New Interceptor, чтобы открыть редактор Custom Action.
  3. Введите Action Name.
  4. В шаблонном коде добавьте свой пользовательский код внутри функции onRequest для перехвата и изменения запроса и внутри функции onResponse для перехвата и изменения ответа.
подсказка

Вы можете скопировать шаблонный код в ChatGPT и запросить завершение для конкретного кода перехватчика. Вот пример. Однако могут потребоваться финальные корректировки.

  1. Save Action и проверьте на наличие ошибок.
  2. Новый созданный перехватчик будет добавлен в список API interceptors.
Дополнительно
  • Вы можете добавить несколько перехватчиков к любому вызову API.
  • Когда один и тот же перехватчик используется несколькими API, вы можете создать группу API и добавить перехватчик в Advanced Group Settings. Однако вы можете переопределить перехватчик для любого API в группе, если хотите.

Посмотрите видео

Если вы предпочитаете видеоурок, вот он для вас:

Часто задаваемые вопросы​

Почему мой предопределенный путь не показывает никаких опций?

Это часто происходит, если вы добавили предопределенный путь, но забыли сохранить вызов API в FlutterFlow. Убедитесь, что вы нажимаете Save после внесения любых изменений в вызов API, чтобы FlutterFlow мог правильно распознать и отобразить ваши предопределенные пути.

Почему я получаю ошибку «Current variable is not valid»?

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