Імпорт даних із зовнішнього 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
    }
  ]
}

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

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

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

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

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

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

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

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

12. Перегляньте зведення «Звіт про імпорт»:

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

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

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