Если вы разработчик программного обеспечения, подумайте, как вы могли бы добавить функции импорта, преобразования и проверки данных в свое веб-приложение всего за несколько минут с помощью JavaScript и React, используя встроенный SDK и библиотеки. Вы можете подумать об использовании SDK, такого как внешняя библиотека Embed React в Flatfile. Если вам нужно определить более сложные правила проверки данных в бэкэнде, вы можете напрямую запросить Flatfile API для управления потоком проверки данных, используя ваш существующий технический стек.

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

Нужен сервис импорта данных

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

Есть и другие причины, которые вы можете придумать, когда вам нужно разрешить прием файлов из стороннего источника, например импорт данных напрямую из Salesforce. Могут быть определенные сценарии, в которых вам потребуются разные правила проверки данных для нескольких сред (разработки, промежуточной или рабочей). В этом случае вы можете настроить эти данные в рабочем процессе Flatfile. Платформы импорта данных, такие как Flatfile, предлагают интуитивно понятный интерфейс и инструменты разработчика, которые упрощают процесс интеграции данных из различных источников и их проверки без необходимости сложного кодирования, самостоятельной реализации или ручного ввода данных. По сути, выбор между созданием и покупкой/использованием существующих программных решений больше не является вопросом компромисса, а скорее является стратегическим решением, которое может объединить преимущества обоих подходов. В то же время эти решения часто поставляются с API и другими параметрами настройки, что позволяет адаптировать их к вашим уникальным требованиям.

При использовании Flatfile API?

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

Представьте, что поставщики медицинских услуг часто имеют дело с картами пациентов и медицинскими данными, которые необходимо импортировать в системы электронных медицинских карт (EHR). Flatfile API может помочь в импорте демографических данных пациента, истории болезни, диагностических отчетов или результатов лабораторных исследований, обеспечивая при этом точность данных и соответствие определенным форматам данных и стандартам.

Импортируйте свои первые данные в Flatfile

В этом разделе вы узнаете, как импортировать данные в Flatfile. Мы начнем с создания новой учетной записи Flatfile и получения ключа API. Затем мы создадим новую Рабочую книгу с помощью API Flatfile и вставим запись в лист.

Предпосылки

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

Ключевые идеи

  • Пространство — это ваше приложение, в котором у вас есть фронтенд, база данных для работы с данными.
  • Рабочие книги — аналог шаблона электронной таблицы или традиционной схемы базы данных, который определяет структуру данных, с которыми вы работаете. В одном пространстве может быть несколько книг.
  • Таблицы — группа полей, предоставляющих описательную информацию о конкретном объекте, например о таблицах в базе данных.
  • Поля — определите характеристику или атрибут объекта, например имя или адрес электронной почты, и укажите его поведение.

Шаг 1: Зарегистрируйте новую учетную запись

Вы можете начать использовать Flatfile бесплатно. Посетите веб-сайт Flatfile по адресу https://flatfile.com/ и зарегистрируйтесь для получения учетной записи. Предоставьте необходимую информацию для создания учетной записи. После регистрации вы получите электронное письмо с подтверждением и инструкциями о том, как подтвердить свою учетную запись.

Шаг 2. Получите учетные данные API

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

Шаг 3. Создайте книгу

Ниже приведен пример добавления новой схемы для записей данных пациента в Flatfile путем создания Рабочей книги с использованием API FlatFile с помощью команды cURL. Важно отметить, что предоставленная команда curl является всего лишь примером, и вам нужно будет заменить PASTE_SECRET_KEY_HERE фактическим секретным ключом для аутентификации запроса.

curl --request POST \
  --url https://platform.flatfile.com/api/v1/workbooks \
  --header 'Authorization: Bearer PASTE_SECRET_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
   "name":"Medical Data Workbook",
   "sheets":[
      {
         "name":"Patient Data Records",
         "slug":"patient_records",
         "fields":[
            {
               "label":"Patient Name",
               "key":"patient_name",
               "type":"string"
            },
            {
               "label":"Gender",
               "key":"gender",
               "type":"string"
            },
            {
               "label":"Date of Birth",
               "key":"dob",
               "type":"date"
            },
            {
               "label":"Diagnosis",
               "key":"diagnosis",
               "type":"string"
            },
            {
               "label":"Treatment",
               "key":"treatment",
               "type":"string"
            }
         ]
      }
   ]
}'

Команда cURL отправляет запрос POST в конечную точку FlatFile API /workbooks с полезными данными JSON. Полезная нагрузка JSON определяет структуру книги с полями, соответствующими записям медицинских данных. После успешного выполнения API создаст книгу и вернет ответ с подробностями, включая spaceId, workbookId и sheetId, которые вы можете использовать для дальнейших операций.

Шаг 4: Импорт данных

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

  • Загрузив файл любого типа, например CSV, Excel, JSON и т. д., вручную в интерфейсе Flatfile Platform в разделе Файлы, а затем щелкнув действие Импорт для файл.
  • Путем встраивания Flatfile в код вашего приложения.
  • Загружая файлы с помощью загрузки Конечная точка API.
  • Добавляя новые записи на лист рабочей книги с помощью Flatfile API.

Мы собираемся вставить одну запись, используя Flatfile API. Для этого нам нужно sheetId добавить записи на конкретный лист и запустить приведенную ниже команду cURL, чтобы отправить запрос в конечную точку вставить записи:

curl --request POST \
  --url https://platform.flatfile.com/api/v1/sheets/{sheetId}/records \
  --header 'Authorization: Bearer PASTE_SECRET_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
   {
      "patient_name":{
         "value":"Jon Woodward",
         "valid":true
      },
      "gender":{
         "value":"male",
         "valid":true
      },
      "dob":{
         "value":"2000-01-01",
         "valid":true
      },
      "diagnosis":{
         "value":"Stomach Ache",
         "valid":true
      },
      "treatment":{
         "value":"Reduce your intake of coffee",
         "valid":true
      }
   }
]'

Тело запроса содержит данные JSON, представляющие запись, которую необходимо создать. В этом примере на листе создается одна запись с такими полями, как patient_name, gender, dob, diagnosis, и treatment вместе с их соответствующие значения и статус проверки.

Шаг 5: Проверьте результат на платформе Flatfile

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

Шаг 6. Введите сообщение проверки

С помощью Flatfile вы также можете сделать входные данные действительными/недействительными, определив правила проверки. В приведенном выше примере мы установили все значения свойств, чтобы они были точными. Тем не менее, вы также можете выполнять проверки своего внутреннего кода или использовать Flatfile SDK, вы можете включить ряд плагинов для преобразования и проверки, чтобы изменить форму данных до их обновления, добавить сообщение об ошибке и обновить записи, чтобы показать, что они недействительны, с необходимыми сообщениями об ошибках. Вам необходимо запросить конечную точку Update Records с помощью recordId, полученного на шаге 3. Ниже показано, как это сделать:

curl --request PUT \
  --url https://platform.flatfile.com/api/v1/sheets/{sheetId}/records \
  --header 'Authorization: Bearer PASTE_SECRET_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '[
   {
      "id":"{recordId}",
      "values":{
         "treatment":{
            "value":"Reduce your intake of coffee",
            "valid":false,
            "messages":[
               {
                  "type":"error",
                  "source":"custom-logic",
                  "message":"Incorrect treatment advice"
               }
            ]
         }
      }
   }
]'

Вывод после того, как мы сделали запись недействительной:

Следующие шаги

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

Рекомендуемые ресурсы

Об авторе