#Использование ключей 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 destroy):

  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"