API проектов

FlutterFlow API проектов позволяют программно читать, записывать и проверять файлы конфигурации в формате YAML через REST-эндпоинты. С помощью этих API вы можете автоматизировать задачи управления проектами, интегрировать рабочие процессы непрерывной интеграции и доставки (CI/CD), а также применять массовые обновления конфигурации без ручного взаимодействия с пользовательским интерфейсом FlutterFlow.

warning

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

Предварительные требования

Перед использованием API YAML проектов убедитесь, что у вас есть следующее:

HTTP-клиент: Используйте инструмент вроде curl, Postman или библиотеку HTTP в вашем предпочитаемом языке программирования (например, axios, requests).
Доступ к проекту: Для операций GET и валидации требуется доступ на чтение, а для внесения обновлений — доступ редактора.
Платный план: Требуется платная подписка FlutterFlow.

Обзор YAML

Что такое YAML проектов FlutterFlow?

YAML (YAML Ain't Markup Language) — это удобный для чтения человеком формат сериализации данных, который обычно используется для файлов конфигурации. В FlutterFlow YAML проектов представляют полное структурное определение вашего приложения, по сути раскрывая полную схему проекта, которая управляет вашим приложением FlutterFlow.

Что включено в схему проекта?

Файлы YAML FlutterFlow содержат всестороннее представление всего вашего проекта, включая:

Компоненты UI и страницы: Деревья виджетов, макеты страниц, иерархии компонентов и конфигурации стилей.
Конфигурация приложения: Настройки, такие как детали приложения, методы аутентификации, интеграции (AdMob, Firebase и т. д.).
Структуры данных: Коллекции базы данных, схемы API, переменные состояния приложения и пользовательские типы данных.
Бизнес-логика: Действия, функции, условная логика и определения рабочих процессов.
Активы и ресурсы: Файлы пользовательского кода, ссылки на изображения, шрифты и другие активы проекта.
Организация проекта: Структуры папок, библиотеки компонентов и метаданные проекта.

YAML против UI FlutterFlow

Каждое изменение, которое вы вносите в визуальном редакторе FlutterFlow — от перетаскивания виджета на страницу до настройки коллекции базы данных — в конечном итоге сохраняется как структурированные данные в этих файлах YAML. UI FlutterFlow предоставляет интуитивно понятный визуальный интерфейс для редактирования этой базовой схемы, в то время как API проектов дает вам прямой программный доступ к тем же данным.

Структура файлов

FlutterFlow автоматически разделяет ваш проект на логические файлы YAML для оптимальной производительности и организации. Каждый файл представляет конкретный аспект вашего проекта (например, app-state, ad-mob, отдельные страницы, коллекции и т. д.), что упрощает целевые обновления без влияния на весь проект.

Базовый URL

FlutterFlow предоставляет разные API-эндпоинты для различных сред. Используйте соответствующий базовый URL ниже в зависимости от ваших нужд:

Production
Beta/Staging
Enterprise

https://api.flutterflow.io/v2/

https://api.flutterflow.io/v2-staging/

India

 https://api-enterprise-india.flutterflow.io/v2/

APAC

https://api-enterprise-apac.flutterflow.io/v2/

US Central

https://api-enterprise-us-central.flutterflow.io/v2/

Europe

https://api-enterprise-europe.flutterflow.io/v2/

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

Все API-эндпоинты требуют аутентификации с использованием Bearer-токена. Вам нужно включить токен API FlutterFlow в заголовок Authorization каждого запроса. См. как получить токен API.

Authorization: Bearer YOUR_API_TOKEN_HERE

API-эндпоинты

Ниже приведен список доступных API-эндпоинтов с их методами и описаниями использования.

Endpoint	Method	Purpose
`/listPartitionedFileNames`	GET	List available YAML file names for a project.
`/l/listProjects`	POST	Retrieve metadata for all projects.
`/projectYamls`	GET	Export/download YAML files from a project.
`/validateProjectYaml`	POST	Validate YAML content before applying changes.
`/updateProjectByYaml`	POST	Update project configuration via YAML.

Список имен файлов

Перед чтением или обновлением файлов проекта вам нужно знать, какие YAML-файлы доступны. Этот эндпоинт возвращает полный список имен файлов, связанных с вашим проектом FlutterFlow.

Endpoint

GET /listPartitionedFileNames

Query Parameters

projectId (required): The ID of the FlutterFlow project

Response

{
  "success":true,
  "reason":null,
  "value":{
    "versionInfo": {
      "partitionerVersion": 6, 
      "projectSchemaFingerprint": "abc123"
    },
    "fileNames": [
      "folders",
      "app-details",
      "collections/id-yr7z6g5a",
      "page/id-Scaffold_l9g6ilb6/page-widget-tree-outline/node/id-Column_174wuhc4",
      "custom-file/id-MAIN/custom-file-code",
      ...
    ]
  }
}

Массив fileNames перечисляет все доступные YAML-файлы. Раздел versionInfo предоставляет метаданные о версии схемы и ее уникальном отпечатке. Если какая-либо часть versionInfo изменится, это указывает на то, что API или структура ответов YAML была обновлена.

Example Usage

curl -X GET \
  'https://api.flutterflow.io/v2/listPartitionedFileNames?projectId=your-project-id' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Список проектов

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

Endpoint

POST /l/listProjects

Request Body

{
  "project_type": "ALL",
  "deserialize_response": true
}

project_type: "ALL": Use "ALL" to include personal, team, and shared projects, or "TEAM_RESOURCE" to include only team-associated projects.
deserialize_response: true: Ensures the response is returned as human-readable JSON instead of a base64-encoded protobuf.

подсказка

Рекомендуется использовать параметры по умолчанию: "ALL" для project_type и true для deserialize_response, чтобы получить наиболее полные и читаемые результаты.

Response

Возвращает JSON-объект, содержащий массив проектов под ключом entries. Каждая запись содержит ID проекта и подробные метаданные, включая участников, иконки приложений, сессии и информацию о ветвях.

{
  "success": true,
  "reason": null,
  "value": {
    "entries": [
      {
        "id": "XXXXXXXXXXXXXXX",
        "project": {
          "name": "Sample Project A",
          "ownerEmail": "user1@example.com",
          "createdAt": "2024-08-08T11:01:12.427Z",
          "updatedAt": "2024-08-08T11:01:18.669Z",
          "teamRef": {
            "path": "teams/TEAM_ID_1"
          },
          "mainBranchRef": {
            "path": "projects/sample-project-id"
          },
          "numBranches": 2,
          "otherMembers": {
            "USER_XYZ": {
              "email": "editor1@example.com",
              "accessLevel": "EDITOR"
            }
          },
          "activeSessions": {
            "SESSION_ID_1": {
              "lastSuccessfulUpdate": "2024-08-06T18:41:56.569Z"
            }
          },
          "totalNumUpdates": 2177
        }
      }
    ]
  }
}

Example Usage

curl 'https://api.flutterflow.io/v2/l/listProjects' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  --data-raw '{
    "project_type": "ALL",
    "deserialize_response": true
  }'

Скачивание YAML проекта

Вы можете скачать конкретные или все YAML-файлы конфигурации из вашего проекта FlutterFlow. Это помогает понять текущую структуру файла перед его модификацией.

Endpoint

GET /projectYamls

Query Parameters

projectId (required): The ID of the FlutterFlow project
fileName (optional): Specific file to export (without extension). If not provided, all files are exported.

Response

Возвращает zip-файл, закодированный как строка base64. Вам нужно будет вручную декодировать эти данные base64 в загружаемый .zip-файл. Для этого скопируйте значение projectYamlBytes и затем вы можете использовать онлайн-инструменты, такие как base64.guru или b64encode.com, чтобы преобразовать и скачать файлы.

{
  "success":true,
  "reason":null,
  "value":{
    "versionInfo": {
      "partitionerVersion": 6,
      "projectSchemaFingerprint": "abc123"
    },
    "projectYamlBytes": "UEsDBAoAAAAAAKxV..."
  }
}

Example Usage

# Export all YAML files
curl -X GET \
  'https://api.flutterflow.io/v2/projectYamls?projectId=your-project-id' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

# Export specific file
curl -X GET \
  'https://api.flutterflow.io/v2/projectYamls?projectId=your-project-id&fileName=ad-mob' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Валидация YAML проекта

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

Endpoint

POST /validateProjectYaml

Request Body

{
  "projectId": "your-project-id",
  "fileKey": "ad-mob",
  "fileContent": "showTestAds: false\nappId: \"your-app-id\""
}

к сведению

В объекте fileContent вы должны предоставить полное содержимое файла.

Содержимое YAML должно передаваться как однострочная строка с правильным форматированием и соответствующим экранированием для новых строк и отступов. Например, в следующем объекте fileContent вы видите фактическое многострочное содержимое YAML, которое не допускается ❌.

{
  "projectId": "ecommerce-flow-app-ie7nl6",
  "fileKey": "app-state",
  "fileContent": "fields:
  - parameter:
      identifier:
        name: myAppState
        key: hg7j8z0y
      dataType:
        scalarType: String
      description: "Stores the current user session state"
    persisted: false"
}

Теперь вот как содержимое YAML должно передаваться (т. е. как однострочная строка ✅).

{
  "projectId": "ecommerce-flow-app-ie7nl6",
  "fileKey": "app-state",
  "fileContent": "fields:\n  - parameter:\n      identifier:\n        name: myAppState\n        key: hg7j8z0y\n      dataType:\n        scalarType: String\n      description: \"Stores the current user session state\"\n    persisted: false"
}

Response

Success (200): YAML is valid - {"success": true, "reason": null, "value": ""}

Error with validation details:

{
  "validationErrors": [
    {
      "message": "Expected bool value",
      "fileKey": "ad-mob",
      "yamlLocation": {
        "line": 1,
        "column": 15
      }
    }
  ]
}

Example Usage

curl -X POST \
  'https://api.flutterflow.io/v2/validateProjectYaml' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "projectId": "your-project-id",
    "fileKey": "ad-mob", 
    "fileContent": "showTestAds: false"
  }'

Обновление YAML проекта

Этот эндпоинт позволяет перезаписать существующие файлы в вашем проекте FlutterFlow, отправив обновленное содержимое YAML.

Endpoint

POST /updateProjectByYaml

Request Body

{
  "projectId": "your-project-id",
  "fileKeyToContent": {
    "ad-mob": "showTestAds: false",
  }
}

к сведению

В объекте fileKeyToContent вы должны предоставить полное содержимое файла.

Содержимое YAML должно передаваться как однострочная строка с правильным форматированием и соответствующим экранированием для новых строк и отступов. Например, в следующем объекте fileKeyToContent вы видите фактическое многострочное содержимое YAML, которое не допускается ❌.

{
  "projectId": "ecommerce-flow-app-ie7nl6",
  "fileKeyToContent": {
    "app-state": "fields:
      - parameter:
      identifier:
        name: myAppState
        key: hg7j8z0y
      dataType:
        scalarType: String
      description: "Stores the current user session state"
    persisted: false"
  }
}

Теперь вот как содержимое YAML должно передаваться (т. е. как однострочная строка ✅).

{
  "projectId": "ecommerce-flow-app-ie7nl6",
  "fileKeyToContent": {
    "app-state": "fields:\n  - parameter:\n      identifier:\n        name: myAppState\n        key: hg7j8z0y\n      dataType:\n        scalarType: String\n      description: \"Stores the current user session state\"\n    persisted: false"
  }
}

Response

Success (200): {"success": true, "reason": null, "value": ""}
Error (400): Validation errors or malformed request.
Error (403): Insufficient permissions or project locked.
Error (404): Project or user not found.

Example Usage

Этот пример обновляет файл ad-mob и добавляет/обновляет переменные состояния приложения.

curl -X POST \
  'https://api.flutterflow.io/v2/updateProjectByYaml' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "projectId": "your-project-id",
    "fileKeyToContent": {
      "ad-mob": "showTestAds: false",
      "app-state": "fields:\n  - parameter:\n      identifier:\n        name: myAppState\n        key: hg7j8z0y\n      dataType:\n        scalarType: String\n      description: \"Stores the current user session state\"\n    persisted: false\n  - parameter:\n      identifier:\n        name: userPreferences\n        key: abc123xy\n      dataType:\n        scalarType: JSON\n      description: \"User settings and preferences\"\n    persisted: true"
    }
  }'

Пример использования API

Давайте разберем практический пример обновления переменной состояния приложения с использованием API проектов.

к сведению

Вы можете скачать и использовать Коллекцию Postman, чтобы быстро протестировать все API проектов FlutterFlow с предзаполненными заголовками, параметрами и примерами запросов.

Сначала мы используем эндпоинт /listPartitionedFileNames, чтобы проверить, существует ли файл app-state в проекте. После подтверждения мы вызываем эндпоинт /projectYamls, чтобы скачать YAML-файл. API возвращает строку, закодированную в base64, представляющую zip-файл, который мы декодируем и скачиваем с помощью инструментов вроде Base64 to ZIP.

Далее мы открываем файл app-state.yaml и обновляем переменную enableDarkMode, устанавливая ее значение persisted в true. Затем мы преобразуем обновленный YAML в правильно экранированную однострочную строку и проверяем его с помощью эндпоинта /validateProjectYaml. Если валидация проходит успешно, мы отправляем окончательное обновление с помощью эндпоинта /updateProjectByYaml.

Обработка ошибок

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

Распространенные ответы об ошибках

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

Status Code	Description	Example Response
400	Bad Request - Invalid JSON or malformed YAML	`"Failed to update project: ad-mob:Expected bool value"`
403	Forbidden - Insufficient permissions	`"You do not have write access to this project"`
404	Not Found - Project or user doesn't exist	`"Project not found"`
500	Internal Server Error	`"Unknown error"`

Ошибки валидации

При неудачной валидации YAML вы получите подробную информацию об ошибке:

{
  "validationErrors": [
    {
      "message": "Unknown field name 'showTestAdsasssdaf'",
      "fileKey": "ad-mob",
      "yamlLocation": {
        "line": 1,
        "column": 1
      }
    }
  ]
}

Лучшие практики

Всегда проверяйте сначала: Перед обновлением YAML проектов используйте эндпоинт валидации, чтобы убедиться, что ваши изменения допустимы:

# 1. Validate the YAML
curl -X POST 'https://api.flutterflow.io/v2/validateProjectYaml' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"projectId": "project-id", "fileKey": "ad-mob", "fileContent": "showTestAds: false"}'

# 2. If validation passes, apply the changes
curl -X POST 'https://api.flutterflow.io/v2/updateProjectByYaml' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"projectId": "project-id", "fileKeyToContent": {"ad-mob": "showTestAds: false"}}'

Обработка блокировок проектов: Проекты могут временно блокироваться во время других операций. Если вы получаете ошибку 403 с упоминанием Project is locked due to ongoing changes. Please try again later., подождите и повторите попытку.

Пакетные обновления: Вы можете обновить несколько файлов в одном запросе, включив несколько записей в fileKeyToContent:

{
  "projectId": "your-project-id",
  "fileKeyToContent": {
    "ad-mob": "showTestAds: false",
    "app-settings": "appName: \"Updated Name\"",
    "authentication": "enableEmailAuth: true"
  }
}

Ограничения по скорости

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

API проектов

Обзор YAML​

Что такое YAML проектов FlutterFlow?​

Что включено в схему проекта?​

YAML против UI FlutterFlow​

Структура файлов​

Базовый URL​

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

API-эндпоинты​

Список имен файлов​

Endpoint​

Query Parameters​

Response​

Example Usage​

Список проектов​

Endpoint​

Request Body​

Response​

Example Usage​

Скачивание YAML проекта​

Endpoint​

Query Parameters​

Response​

Example Usage​

Валидация YAML проекта​

Endpoint​

Request Body​

Response​

Example Usage​

Обновление YAML проекта​

Endpoint​

Request Body​

Response​

Example Usage​

Пример использования API​

Обработка ошибок​

Распространенные ответы об ошибках​

Ошибки валидации​

Лучшие практики​

Ограничения по скорости​

Обзор YAML

Что такое YAML проектов FlutterFlow?

Что включено в схему проекта?

YAML против UI FlutterFlow

Структура файлов

Базовый URL

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

API-эндпоинты

Список имен файлов

Endpoint

Query Parameters

Response

Example Usage

Список проектов

Endpoint

Request Body

Response

Example Usage

Скачивание YAML проекта

Endpoint

Query Parameters

Response

Example Usage

Валидация YAML проекта

Endpoint

Request Body

Response

Example Usage

Обновление YAML проекта

Endpoint

Request Body

Response

Example Usage

Пример использования API

Обработка ошибок

Распространенные ответы об ошибках

Ошибки валидации

Лучшие практики

Ограничения по скорости