---
title: "Импорт данных"
description: "Загрузка таблиц в ресурс с сопоставлением колонок и проверкой строк"
canonical_url: "https://frame.qubeek.io/ru/developers/resources/import"
---
# Импорт данных

> Загрузка таблиц в ресурс с сопоставлением колонок и проверкой строк

Импорт ресурса загружает CSV, TSV, XLSX или ODS через панель. Сначала Frame разбирает файл и показывает строки для проверки. Запись в модели выполняется отдельным этапом после подтверждения.

Не путайте этот процесс с `php artisan frame:import-resources`: Artisan-команда переносит существующие записи в поисковый индекс, а не загружает таблицу в БД.

## Этапы обработки

Пользователь загружает файл, проверяет соответствие колонок полям и исправляет сопоставление при необходимости. Frame выполняет проверку строк в фоне. Изменение сопоставления запускает повторную проверку.

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

По умолчанию колонки и правила берутся из полей создания ресурса. Без настройки ключей сопоставления каждая строка создаёт новую запись, в том числе при повторной загрузке файла.

## Определение импорта

Вынесите правила в наследника `ResourceImport`. Пример обновляет запись при совпадении `external_id`, иначе создаёт новую:

```php [app/Frame/Imports/PostImport.php]
<?php

declare(strict_types=1);

namespace App\Frame\Imports;

use Frame\Laravel\Imports\ResourceImport;

final class PostImport extends ResourceImport
{
    public function uniqueBy(): array
    {
        return [['external_id']];
    }

    public function rules(): array
    {
        return [
            'external_id' => ['required', 'string'],
            'title' => ['required', 'string', 'max:255'],
        ];
    }
}
```

Поля `external_id` и `title` должны быть объявлены среди полей создания ресурса либо в явном наборе `columns()` определения импорта. Правила `rules()` переопределяют правила соответствующих полей.

Подключите класс в ресурсе:

```php [app/Frame/Resources/PostResource.php]
use App\Frame\Imports\PostImport;
use Frame\Laravel\Options\Options;

protected function setUp(Options $options): void
{
    $options->import->using(PostImport::class);
}
```

`uniqueBy()` возвращает список ключей в порядке приоритета. Составной ключ задаётся одним вложенным массивом, например `[['source', 'external_id']]`. Выбирайте бизнес-ключ, однозначно определяющий запись; для целостности данных задайте соответствующее ограничение в БД.

## Дополнительные настройки

Для простого случая можно задать ключ без отдельного класса:

```php [app/Frame/Resources/PostResource.php]
protected function setUp(Options $options): void
{
    $options->import->uniqueBy('external_id');
}
```

Определение `ResourceImport` также поддерживает `columns()`, `messages()`, `prepare()`, `beforeSave()` и `afterSave()`. Для собственной записи строки предусмотрен `importer()`. Эти хуки выполняются на сервере; не переносите в них доверие к пользовательским колонкам или обход проверок доступа.

`normalizeSelectLabels()` по умолчанию включён: подпись опции Select преобразуется в её значение перед валидацией. Вызовите `$options->import->normalizeSelectLabels(false)`, если файл должен содержать только значения.

## Очередь и хранилище

Разбор файла и повторная проверка выполняются заданиями Laravel Queue. Для них настройте асинхронное подключение и worker. Подтверждение через API панели запускает сохранение внутри потокового HTTP-запроса с прогрессом SSE; серверный `ImportService::commit()` предоставляет отдельный путь через очередь.

По умолчанию параметры очереди и диска наследуются от [экспорта](https://frame.qubeek.io/ru/developers/resources/export#%D0%BE%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C-%D0%B8-%D1%85%D1%80%D0%B0%D0%BD%D0%B8%D0%BB%D0%B8%D1%89%D0%B5); их можно разделить:

```ini [.env]
FRAME_IMPORTS_QUEUE=frame_imports
FRAME_IMPORTS_DISK=local
```

```shell
php artisan queue:work --queue=frame_imports
```

Web-процесс и worker должны видеть один диск с исходным файлом и буфером строк. При нескольких узлах используйте общее хранилище и общий cache для состояния обработки. Не открывайте каталог импортов как публичную файловую раздачу.

## Что дальше

- [Создание схемы](https://frame.qubeek.io/ru/developers/resources/creation) — объявите модель и поля ресурса.
- [Валидация полей](https://frame.qubeek.io/ru/developers/fields/validation) — задайте правила значений.
- [Авторизация ресурса](https://frame.qubeek.io/ru/developers/resources/authorization) — настройте права пользователей.
- [Экспорт](https://frame.qubeek.io/ru/developers/resources/export) — настройте обратную выгрузку в XLSX.


## Sitemap

See the full [sitemap](https://frame.qubeek.io/sitemap.md) for all pages.
