Імпорт даних із зовнішнього API

У цій статті описано, як використовувати функцію імпорту для імпорту даних із зовнішнього інтерфейсу прикладного програмування (API), а також наведено вимоги до формату API.

Щоб виконати цей процес, вам потрібні наступні ролі та дозволи:

• Дозвіл "Додати записи" для цільової форми
• Дозвіл "Редагувати записи", якщо ви оновлюєте наявні записи
• Дозвіл "Додавати форми, папки та звіти" (щоб мати можливість створювати дизайн форми, якщо вам потрібна нова форма)

Підтримуваний формат вихідних даних

• API має надавати відповідь у форматі JSON
• Відповідь JSON має містити масив об'єктів JSON, наприклад:

[
  { "name": "North Kivu", "code": "RD001" },
  { "name": "South Kivu", "code": "RD002" },
  { "name": "Ituri", "code": "RD003" }
]

• Вкладені об'єкти підтримуються, тому наступний приклад буде прийнятним:

{ "status": "OK",
  "data": 
    [  
      { "name": "North Kivu", "code": "RD001" },
      { "name": "South Kivu", "code": "RD002" }, 
      { "name": "Ituri", "code": "RD003" }
    ]
}

• Назви полів мають бути послідовними, тому наступний приклад не спрацює:

[
  { "location": "North Kivu" },
  { "loc": "South Kivu" },
  { "Location": "Ituri" }
]

• Кінцева точка API має підтримувати HTTP-запит GET

• Якщо API не є загальнодоступним, підтримуються два типи заголовків Authorization:

• Базова автентифікація доступу: ім'я користувача та пароль у кодуванні Base64

• Токен Bearer: єдиний секретний токен. ActivityInfo надсилатиме заголовок Authorization у форматі “Bearer <токен>” як частину запиту

• Доступний через HTTPS

Імпорт даних з API

Щоб імпортувати дані з API за допомогою функції імпорту, виконайте наступні кроки:

1. Перевірте, чи відповідаєте ви попереднім вимогам:

• Мати обліковий запис ActivityInfo
• Доступ до форми
• Відповідні дозволи

2. Створіть форму, в яку ви будете імпортувати дані. Важливо визначити структуру форми перед імпортом даних.
   Якщо у вас вже є форма, перейдіть до її подання у вигляді таблиці.
3. Виберіть інструмент "Імпорт" на панелі інструментів.

4. Натисніть "З API".

5. Налаштуйте імпорт з API, заповнивши наступні поля:

• URL API: вставте посилання сюди. Підтримуються лише безпечні протоколи (https).
• Виберіть метод автентифікації, залежно від зовнішнього сервісу: "Не знайдено" для загальнодоступного API, наприклад; "Токен Bearer" або "Базова автентифікація". Зверніться до документації API, який ви використовуєте, щоб визначити, який метод автентифікації підтримується.

6. Натисніть "Продовжити" і зачекайте, поки дані завантажаться.
7. Виберіть шлях до даних у вікні "Перегляд даних". Якщо API не надає масив об'єктів безпосередньо, вам потрібно вибрати шлях до масиву для імпорту.
   У цьому прикладі виберіть “data” як шлях запиту API.

Якщо у випадаючому списку доступно кілька шляхів до даних, вам потрібно визначити, яку частину відповіді ви хочете імпортувати.
У цьому прикладі ви можете побачити, що у відповіді API є два масиви об'єктів (“provinces” та “changes”):

{
  "status": "OK",
  "provinces": [
    {
      "name": "North Kivu",
      "code": "RD001"
    },
    {
      "name": "South Kivu",
      "code": "RD002"
    }
  ],
  "changes": [
    { 
      "date": "2025-01-01",
      "version": 1
    },
    {
      "date": "2025-03-02",
      "version": 2
    }
  ]
}

Ви не можете імпортувати обидва масиви одночасно, вам потрібно вибрати один шлях до даних з випадаючого списку.

7. Натисніть "Продовжити" і зачекайте, поки завантажаться записи.

8. Час зіставити колонки та перевірити поля, натискаючи на кожну виділену колонку, щоб вирішити проблеми. Для отримання додаткової інформації див. Усунення несправностей, пов'язаних з імпортом.
   На цьому кроці ви можете використовувати фільтри, щоб обмежити дані, які ви хочете імпортувати.

Фільтрація недоступна для значень полів з множинним посиланням та незіставлених полів. Зіставлення цільових полів не підтримується.

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

9. Після усунення невідповідностей натисніть "Продовжити" у верхньому правому куті.
10. Користувачі з дозволом "Керування конфігураціями імпорту" можуть зберегти цю конфігурацію імпорту для повторного імпорту даних та поділитися нею з іншими користувачами бази даних. Збережені конфігурації не запускаються автоматично.

Опція збереженої конфігурації включає в себе наступні аспекти:

• Джерело імпорту ("З API" в цьому випадку)
• URL API, авторизація, шлях до даних
• Зіставлення полів, включаючи постійні значення
• Фільтри, якщо застосовано
• Облікові дані зберігаються, якщо ви використовуєте автентифікацію на цьому кроці. Хоча облікові дані невидимі для інших користувачів, майте на увазі, що будь-хто з дозволом на керування конфігурацією імпорту зможе використовувати збережені облікові дані для повторного запуску імпорту в майбутньому.

11. Перегляньте зведення "Звіт про імпорт":

• Якщо все правильно, перейдіть до наступного кроку.
• Якщо вам потрібно почати спочатку, натисніть "Скасувати".
• Щоб повернутися до частини процесу зіставлення колонок та перевірки полів, натисніть "Назад".
• Перемкніть перемикач "Зберегти конфігурацію", щоб зберегти цю конфігурацію імпорту, і натисніть "Продовжити" у спливаючому вікні.

12. Якщо ви зберігаєте конфігурацію, введіть назву для збереженої конфігурації, а потім натисніть "Зберегти та імпортувати записи" у верхньому правому куті.

13. Якщо ви не зберігаєте налаштування конфігурації, натисніть "Імпорт записів" у верхньому правому куті та зачекайте, поки завантажаться оновлення.