> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge-ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge-ru/rukovodstva/rukovodstvo-administratora/kak-sokhranyat-artefakty-instant-api-v-khranilishe-s3.md).

# Как сохранять артефакты Instant API в хранилище S3

{% hint style="warning" icon="display" %}
Внимание: это машинный перевод.
{% endhint %}

По умолчанию Instant API (режим без сохранения данных) нигде не сохраняет данные — результаты анализа сразу возвращаются в HTTP-ответе, и ничего не записывается. Начиная с API 6.4.1, доступна опциональная функция сохранения артефактов анализа во внешнее хранилище для отладки и расследования инцидентов.

Instant API возвращает результаты клиенту независимо от того, успешно ли прошло сохранение, — процесс сохранения изолирован от основного процесса анализа.

### Что сохраняется

Если функция включена, для каждого запроса на анализ в папку, идентифицируемую по `folder_id`, сохраняются следующие артефакты:

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Файл</th><th>Шаблон имени</th><th>Описание</th></tr></thead><tbody><tr><td>Данные инициализации контейнера (для сценария с контейнером)</td><td><code>init_container.dat</code></td><td>Исходные данные контейнера</td></tr><tr><td>Ответ движка</td><td><code>{source_media_id}_engine_response.json</code></td><td>Необработанный ответ движка (по одному файлу на каждый анализируемый медиафайл)</td></tr><tr><td>Тело запроса</td><td><code>payload.json</code></td><td>Исходное тело запроса</td></tr><tr><td>Ответ API</td><td><code>response.json</code></td><td>Полный ответ Instant API (включая <code>image_b64</code> для best shot и, начиная с 6.6.1, action shot)</td></tr><tr><td><code>&#x3C;original_name></code></td><td>Без шаблона</td><td>Исходное имя медиафайла</td></tr></tbody></table>

Невалидные контейнеры (не прошедшие валидацию) также сохраняются.

{% hint style="info" %}
В режиме Instant поля `original_url` и `thumb_url` в ответе API остаются `null`, даже если сохранение включено. Сохраненные данные — это только дамп в хранилище; эндпойнта API для их получения нет.
{% endhint %}

### Настройка

#### Включение функции

По умолчанию сохранение отключено. Чтобы включить его, установите для [`OZ_INSTANT_SAVING_ARTIFACTS_ENABLED`](#user-content-fn-1)[^1] значение `true` (по умолчанию: `false`). Если функция включена, артефакты сохраняются в соответствии со значением `OZ_FILE_STORAGE_TYPE` (`LOCAL` или `S3`), а не только в S3.

#### Тип хранилища

Пример (S3-хранилище):

```shell
OZ_FILE_STORAGE_TYPE: "S3"
OZ_LOCAL_STORAGE_SUPPORT_ENABLE: "true"
OZ_S3_STORAGE_SUPPORT_ENABLE: "true"
```

* `OZ_FILE_STORAGE_TYPE` — `LOCAL` или `S3`. Определяет, куда записываются артефакты.
* `OZ_S3_STORAGE_SUPPORT_ENABLE` — для работы с S3 должен иметь значение `true`; определяется значением `OZ_FILE_STORAGE_TYPE`.
* `OZ_LOCAL_STORAGE_SUPPORT_ENABLE` — включает поддержку локального хранилища. В SaaS поддержка локального хранилища и S3 включена одновременно, поэтому для этого параметра также следует установить значение `true`.

Для корректной настройки обратитесь к документации из комплекта поставки для используемого вами способа установки.

#### Параметры подключения к S3

{% hint style="info" %}
Для `OZ_FILE_STORAGE_TYPE=S3`.
{% endhint %}

**Обязательные**

| Параметр                    | Описание                                                           |
| --------------------------- | ------------------------------------------------------------------ |
| `OZ_STATIC_S3_BASE_URL`     | Базовый URL для формирования публичных ссылок на статические файлы |
| `OZ_STATIC_S3_BUCKET`       | Имя S3-бакета                                                      |
| `OZ_STATIC_S3_ENDPOINT_URL` | URL эндпойнта S3                                                   |

**Опциональные**

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Параметр</th><th>Описание</th><th>По умолчанию</th></tr></thead><tbody><tr><td><code>OZ_STATIC_S3_SUFFIX</code></td><td>Префикс пути внутри бакета</td><td><code>oz-media</code></td></tr><tr><td><code>OZ_STATIC_S3_BUCKET_URL</code></td><td>URL S3-бакета (начиная с 6.5.0, можно оставить пустым)</td><td><code>""</code></td></tr><tr><td><code>OZ_STATIC_S3_ACCESS_KEY</code></td><td>Ключ доступа S3</td><td><code>None</code></td></tr><tr><td><code>OZ_STATIC_S3_SECRET_KEY</code></td><td>Секретный ключ S3</td><td><code>None</code></td></tr><tr><td><code>OZ_STATIC_S3_REGION_NAME</code></td><td>Название региона AWS</td><td><code>None</code></td></tr></tbody></table>

#### Формат пути

* `OZ_MEDIA_STATIC_FOLDER_FORMAT` — формат `strftime` для части пути в хранилище, содержащей дату (по умолчанию: `%Y/%m/%d/%H`)

#### Права доступа к S3-бакету

Для IAM-роли или пользователя, обращающегося к бакету, требуются следующие действия S3:

* `s3:ListBucket` (для ресурса бакета)
* `s3:GetObject` (для объектов в бакете)
* `s3:PutObject` (для объектов в бакете)
* `s3:DeleteObject` (для объектов в бакете)

`ListBucket` используется при удалении: API получает список всех объектов с префиксом папки, затем удаляет их по одному. В S3 нет встроенной операции удаления папки.

Пример политики AWS IAM:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListBucket",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
    },
    {
      "Sid": "ObjectOperations",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
    }
  ]
}
```

#### Влияние авторизации

* `OZ_AUTHORIZE_DISABLED_STATELESS` — при значении `true` (типично для Instant) `company_id` в пути хранилища принимает значение `00000000-0000-0000-0000-000000000000`. При значении `false` `company_id` берется из JWT.

#### Пример запуска в Docker

```shell
sudo docker run -d -it \
  --name instant \
  -p 8081:8080 \
  -e OZ_INSTANT_SAVING_ARTIFACTS_ENABLED=true \
  -e OZ_STATIC_S3_SUFFIX=instant \
  -e OZ_STATIC_S3_BUCKET=<bucket> \
  -e OZ_STATIC_S3_ACCESS_KEY=<key> \
  -e OZ_STATIC_S3_SECRET_KEY=<secret> \
  -e OZ_STATIC_S3_ENDPOINT_URL=<endpoint_url> \
  -e OZ_STATIC_S3_BUCKET_URL=<bucket_url> \
  -e OZ_STATIC_S3_REGION_NAME=<region> \
  -e OZ_STATIC_S3_BASE_URL=<base_url> \
  -e OZ_FILE_STORAGE_TYPE=S3 \
  <api-instant-image>:<tag>
```

### Путь в хранилище

```
s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/{company_id}/{OZ_MEDIA_STATIC_FOLDER_FORMAT}/{folder_id}/
```

Где:

* `OZ_MEDIA_STATIC_FOLDER_FORMAT` по умолчанию — `%Y/%m/%d/%H` (например, `2025/12/18/09`)
* `company_id` = `00000000-0000-0000-0000-000000000000`. Если авторизация включена (`OZ_AUTHORIZE_DISABLED_STATELESS=false`), `company_id` берется из компании аутентифицированного пользователя.

Пример: `s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/00000000-0000-0000-0000-000000000000/2025/12/18/09/11111111-1111-1111-1111-111111111111/`

<details>

<summary>Формат пути в Full API (для справки)</summary>

В режиме Full API в базе данных хранится полный путь S3, включая бакет и суффикс:

```
s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/11111111-.../2026/04/09/09/.../media_id.jpeg
```

В ответе API `s3://` заменяется публичным URL:

```
{PROTOCOL}://{API_HOSTNAME}/static/{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/...
```

Для локального хранилища замена выглядит так: `{PROTOCOL}://{API_HOSTNAME}/static/`.

</details>

### Instant API и Full API — сравнение работы с хранилищем

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Аспект</th><th>Instant API</th><th>Full API</th></tr></thead><tbody><tr><td>Хранение по умолчанию</td><td>Ничего не хранится</td><td>Все медиафайлы и результаты хранятся в БД и файловом хранилище</td></tr><tr><td>Требуется переключатель</td><td>Да (<code>OZ_INSTANT_SAVING_ARTIFACTS_ENABLED</code>)</td><td>Нет (хранение — базовая функция)</td></tr><tr><td>Что сохраняется</td><td>медиафайлы, payload, response, engine_response</td><td>медиафайлы, результаты анализа, миниатюры, best shot, action shot</td></tr><tr><td><code>original_url</code> в ответе</td><td>Всегда <code>null</code></td><td>Публичный URL статического файла</td></tr><tr><td><code>thumb_url</code> в ответе</td><td>Всегда <code>null</code></td><td>Публичный URL миниатюры</td></tr><tr><td>Записи в БД</td><td>Нет (stateless)</td><td>Полные записи о папках, медиафайлах и анализах</td></tr><tr><td>Путь в хранилище</td><td><code>s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/{company_id}/{OZ_MEDIA_STATIC_FOLDER_FORMAT}/{folder_id}/</code>; не возвращается клиенту</td><td>Хранится в БД как <code>s3://{OZ_STATIC_S3_BUCKET}/{OZ_STATIC_S3_SUFFIX}/folders/...</code>; в ответе преобразуется в <code>{PROTOCOL}://{API_HOSTNAME}/static/...</code></td></tr><tr><td>Удаление данных через API</td><td>Неприменимо</td><td><code>DELETE /api/folders/{id}</code> удаляет данные из БД и хранилища</td></tr></tbody></table>

[^1]: **Для версии 6.5.0 и новее**;

    В версии 6.4.1 параметр назывался `OZ_INSTANT_SAVING_ARTIFACTS_IN_S3_ENABLED`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.ozforensics.com/oz-knowledge-ru/rukovodstva/rukovodstvo-administratora/kak-sokhranyat-artefakty-instant-api-v-khranilishe-s3.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.