#Використання ключів API в NocoBase

Цей посібник демонструє, як використовувати ключі API в NocoBase для отримання даних на практичному прикладі "Списку справ". Дотримуйтесь покрокових інструкцій нижче, щоб зрозуміти повний робочий процес.

#1 Розуміння ключів API

Ключ API – це безпечний токен, який використовується для автентифікації запитів API від авторизованих користувачів. Він слугує обліковими даними, що підтверджують особу запитувача під час доступу до системи NocoBase через веб-застосунки, мобільні додатки або серверні скрипти.

У заголовку HTTP-запиту ви побачите такий формат:

Authorization: Bearer {API ключ}

Префікс "Bearer" вказує, що наступний рядок є автентифікованим ключем API, який використовується для перевірки дозволів запитувача.

#Типові сценарії використання

Ключі API зазвичай використовуються в таких сценаріях:

1. Доступ для клієнтських застосунків: Веб-браузери та мобільні додатки використовують ключі API для автентифікації користувачів, гарантуючи, що лише авторизовані користувачі можуть отримати доступ до даних.
2. Виконання автоматизованих завдань: Фонова обробка та заплановані завдання використовують ключі API для безпечного виконання оновлень, синхронізації даних та операцій журналювання.
3. Розробка та тестування: Розробники використовують ключі API під час налагодження та тестування для імітації автентифікованих запитів та перевірки відповідей API.

Ключі API надають численні переваги безпеки: перевірка особи, моніторинг використання, обмеження частоти запитів та запобігання загрозам, що забезпечує стабільну та безпечну роботу NocoBase.

#2 Створення ключів API в NocoBase

#2.1 Активуйте плагін "Автентифікація: Ключі API"

Переконайтеся, що вбудований плагін "Автентифікація: Ключі API" активовано. Після активації в системних налаштуваннях з'явиться нова сторінка конфігурації ключів API.

#2.2 Створіть тестову колекцію

Для демонстраційних цілей створіть колекцію з назвою todos з такими полями:

• id
• title
• completed

Додайте кілька зразків записів до колекції:

• їсти
• спати
• грати в ігри

#2.3 Створіть та призначте роль

Ключі API прив'язані до ролей користувачів, і система визначає дозволи на запити на основі призначеної ролі. Перш ніж створювати ключ API, необхідно створити роль та налаштувати відповідні дозволи. Створіть роль з назвою "Роль API для списку справ" і надайте їй повний доступ до колекції todos.

Якщо "Роль API для списку справ" недоступна під час створення ключа API, переконайтеся, що поточному користувачеві призначено цю роль:

Після призначення ролі оновіть сторінку та перейдіть на сторінку керування ключами API. Натисніть "Додати ключ API", щоб перевірити, чи з'явилася "Роль API для списку справ" у виборі ролі.

Для кращого контролю доступу розгляньте можливість створення спеціального облікового запису користувача (наприклад, "Користувач API для списку справ") виключно для керування та тестування ключів API. Призначте цьому користувачеві "Роль API для списку справ".

#2.4 Згенеруйте та збережіть ключ API

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

Приклад ключа API:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M

#2.5 Важливі примітки

• Термін дії ключа API визначається налаштуваннями терміну дії, встановленими під час його створення.
• Генерація та перевірка ключів API залежить від змінної середовища APP_KEY. Не змінюйте цю змінну, оскільки це призведе до анулювання всіх наявних ключів API в системі.

#3 Тестування автентифікації за допомогою ключа API

#3.1 Використання плагіна "Документація API"

Відкрийте плагін "Документація API", щоб переглянути методи запитів, URL-адреси, параметри та заголовки для кожної кінцевої точки API.

#3.2 Розуміння базових операцій CRUD

NocoBase надає стандартні API CRUD (Create, Read, Update, Delete) для маніпуляцій з даними:

• Запит списку (API list):

  GET {baseURL}/{collectionName}:list
  Заголовок запиту:
  - Authorization: Bearer <API ключ>
  

• Створення запису (API create):

  POST {baseURL}/{collectionName}:create
  
  Заголовок запиту:
  - Authorization: Bearer <API ключ>
  
  Тіло запиту (у форматі JSON), наприклад:
      {
          "title": "123"
      }

• Оновлення запису (API update):

  POST {baseURL}/{collectionName}:update?filterByTk={id}
  Заголовок запиту:
  - Authorization: Bearer <API ключ>
  
  Тіло запиту (у форматі JSON), наприклад:
      {
          "title": "123",
          "completed": true
      }

• Видалення запису (API delete):

  POST {baseURL}/{collectionName}:destroy?filterByTk={id}
  Заголовок запиту:
  - Authorization: Bearer <API ключ>

Де:

• {baseURL}: URL-адреса вашої системи NocoBase
• {collectionName}: Назва колекції

Приклад: Для локального екземпляра за адресою localhost:13000 з колекцією todos:

http://localhost:13000/api/todos:list

#3.3 Тестування за допомогою Postman

Створіть GET-запит у Postman з такою конфігурацією:

• URL: Кінцева точка запиту (наприклад, http://localhost:13000/api/todos:list)
• Headers: Додайте заголовок Authorization зі значенням:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M

Успішна відповідь:

{
    "data": [
        {
            "createdAt": "2025-03-03T09:57:36.728Z",
            "updatedAt": "2025-03-03T09:57:36.728Z",
            "completed": null,
            "createdById": 1,
            "id": 1,
            "title": "eat food",
            "updatedById": 1
        }
    ],
    "meta": {
        "count": 1,
        "page": 1,
        "pageSize": 20,
        "totalPage": 1
    }
}

Відповідь про помилку (недійсний/прострочений ключ API):

{
    "errors": [
        {
            "message": "Your session has expired. Please sign in again.",
            "code": "INVALID_TOKEN"
        }
    ]
}

Вирішення проблем: Якщо автентифікація не вдається, перевірте дозволи ролі, прив'язку ключа API та формат токена.

#3.4 Експорт коду запиту

Postman дозволяє експортувати запит у різних форматах. Приклад команди cURL:

curl --location 'http://localhost:13000/api/todos:list' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M'

#4 Використання ключів API в JS-блоці

NocoBase 2.0 підтримує написання нативного JavaScript-коду безпосередньо на сторінках за допомогою JS-блоків. Цей приклад демонструє, як отримати зовнішні дані API за допомогою ключів API.

#Створення JS-блоку

На сторінці NocoBase додайте JS-блок і використайте наступний код для отримання даних списку справ:

// Отримання даних списку справ за допомогою ключа API
async function fetchTodos() {
  try {
    // Показати повідомлення про завантаження
    ctx.message.loading('Отримання даних...');

    // Завантажити бібліотеку axios для HTTP-запитів
    const axios = await ctx.requireAsync('https://cdn.jsdelivr.net/npm/axios@1.6.0/dist/axios.min.js');

    if (!axios) {
      ctx.message.error('Не вдалося завантажити HTTP-бібліотеку');
      return;
    }

    // Ключ API (замініть на ваш фактичний ключ API)
    const apiKey = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInJvbGVOYW1lIjoidG9kb3MiLCJpYXQiOjE3NDA5OTY1ODAsImV4cCI6MzMyOTg1OTY1ODB9.tXF2FCAzFNgZFPXqSBbWAfEvWkQwz0-mtKnmOTZT-5M';

    // Зробити запит до API
    const response = await axios.get('http://localhost:13000/api/todos:list', {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });

    // Показати результати
    console.log('Список справ:', response.data);
    ctx.message.success(`Успішно отримано ${response.data.data.length} елементів`);

    // Тут ви можете обробити дані
    // Наприклад: відобразити в таблиці, оновити поля форми тощо

  } catch (error) {
    console.error('Помилка отримання даних:', error);
    ctx.message.error('Не вдалося отримати дані: ' + error.message);
  }
}

// Виконати функцію
fetchTodos();

#Ключові моменти

• ctx.requireAsync(): Динамічно завантажує зовнішні бібліотеки (наприклад, axios) для HTTP-запитів
• ctx.message: Відображає сповіщення користувача (завантаження, успіх, повідомлення про помилки)
• Автентифікація за допомогою ключа API: Передавайте ключ API у заголовку Authorization з префіксом Bearer
• Обробка відповіді: Обробляйте отримані дані за потреби (відображення, перетворення тощо)

#5 Підсумок

Цей посібник охопив повний робочий процес використання ключів API в NocoBase:

1. Налаштування: Активація плагіна "Ключі API" та створення тестової колекції
2. Конфігурація: Створення ролей з відповідними дозволами та генерація ключів API
3. Тестування: Перевірка автентифікації за допомогою ключа API за допомогою Postman та плагіна "Документація API"
4. Інтеграція: Використання ключів API в JS-блоках

Додаткові ресурси:

• Документація плагіна "Ключі API"
• Плагін "Документація API"