[Документация Yandex Cloud](../../index.md) > [Yandex Object Storage](../index.md) > [Концепции](index.md) > Выгрузка метаданных объектов

# Выгрузка метаданных объектов (S3 Inventory)


{% note warning %}

Функциональность доступна только в [регионе Россия](../../overview/concepts/region.md).

{% endnote %}


В Object Storage вы можете выгрузить [метаданные](object.md#metadata) объектов (S3 Inventory) из бакетов для дальнейшего анализа и каталогизации. Данные выгружаются в другой бакет в формате [CSV](https://ru.wikipedia.org/wiki/CSV) и включают размер, дату создания, MD5-сумму, [класс хранения](storage-class.md), данные [версионирования](versioning.md), [ACL объектов](acl.md) и другое.

Выгрузка метаданных всех объектов будет полезна для следующих задач:

* поиск и анализ данных;
* очистка бакета от дубликатов файлов;
* упрощение синхронизации с другими хранилищами и сервисами;
* улучшение [наблюдаемости (observability)](../../glossary/observability.md);
* реализация сценариев резервного копирования и восстановления версионированных данных.

## Механизм выгрузки {#how-work}

Выгрузка S3 Inventory представляет собой список объектов с метаданными, сформированный по принципу [Eventual consistency](https://ru.wikipedia.org/wiki/Согласованность_в_конечном_счёте). Этот список не является атомарным и консистентным снимком метаданных объектов.

Такой принцип выбран, поскольку для обеспечения горизонтального масштабирования отказоустойчивости и доступности данные в хранилище Object Storage разбиты на отдельные сегменты — _шарды_, и чтобы формирование выгрузок не влияло на производительность работы с бакетом, опрос всех шардов хранилища происходит асинхронно.

Если во время формирования выгрузки объекты были записаны в шард, который уже был просканирован, то конкретно в эту выгрузку данные об этих объектах не попадут. Аналогично работает и удаление объектов. Это стандартная ситуация при выполнении операций `LIST` в бакете.

{% note tip %}

Перед тем как произвести какое-либо действие с объектом из выгрузки, рекомендуется проверить его актуальное состояние с помощью метода `HeadObject` в соответствии с [инструкцией](../operations/objects/object-meta.md#get-object-meta).
 
{% endnote %}

## Исходный и целевой бакеты {#source-destination-buckets}

Бакет, из которого выгружаются метаданные, называется _исходным бакетом_. Такой бакет содержит конфигурацию выгрузки и объекты, метаданные которых нужно выгрузить. Вы можете получить метаданные всех объектов исходного бакета или отфильтровать объекты по папке (префиксу).

Бакет, в который будут записаны выгружаемые метаданные, называется _целевым бакетом_. Чтобы сгруппировать файлы выгрузки в целевом бакете, в конфигурации можно указать префикс для выгрузки.

### Требования {#requirements}

* Исходный и целевой бакеты могут совпадать.
* Исходный и целевой бакеты должны находиться в одном [облаке](../../resource-manager/concepts/resources-hierarchy.md#cloud).
* На целевом бакете не должно быть включено [шифрование](../operations/buckets/encrypt.md).

{% note info %}

Чтобы записывать отчеты в целевой бакет, для которого настроена [политика доступа](policy.md), [добавьте](../operations/buckets/policy.md#apply-policy) в нее правило, разрешающее всем учетным записям выполнять действие `PutObject`, а в качестве ресурса укажите `<префикс_выгрузки>/`.

{% endnote %}

## Конфигурация выгрузки и типы метаданных {#config}

{% note info %}

В Yandex Cloud CLI функциональность доступна с версии CLI 0.193.0 и выше.

{% endnote %}

Вы можете [создать конфигурацию выгрузки](../operations/buckets/manage-s3-inventory.md#create-inventory) с помощью Yandex Cloud CLI или Yandex Cloud API. В конфигурации указываются следующие параметры:

* имя конфигурации;
* целевой бакет и префикс, по которому будет произведена выгрузка;
* периодичность создания отчетов — ежедневно или еженедельно;
* включаемые [версии](versioning.md) объектов — текущие или все версии;
* опциональный префикс для фильтрации объектов, которые попадут в отчет;
* статус конфигурации: включена или выключена;
* список опциональных метаданных объектов.

### Периодичность создания отчетов {#schedule}

В зависимости от заданной периодичности выгрузка начинается:

* ежедневно (`DAILY`) — в 03:00 UTC каждый день;
* еженедельно (`WEEKLY`) — в 03:00 UTC каждое воскресенье.

Например, если создать конфигурацию с ежедневной выгрузкой в 12:00 UTC, то первая выгрузка начнется только в 03:00 UTC следующего дня.

{% note info %}

Время начала выгрузки в будущем может измениться. Не рекомендуем привязывать к нему важные процессы.

{% endnote %}

### Типы метаданных {#metadata-types}

Отчет выгрузки содержит список объектов в исходном бакете и метаданные для каждого перечисленного объекта. Всегда включает следующие поля:

* `BUCKET_NAME` — имя исходного бакета;
* `KEY` — [ключ объекта](object.md#key).

Если выгрузка осуществляется по всем версиям объектов, то также будут добавлены:

* `VERSION_ID` — идентификатор версии;
* `IS_LATEST` — флаг последней версии;
* `DELETE_MARKER` — флаг маркера удаления.

Опциональные метаданные, которые можно указать в конфигурации:

* `SIZE` — размер в байтах, кроме размера незавершенных частей [составных загрузок](multipart.md), метаданных объекта и маркеров удаления;
* `LAST_MODIFIED_DATE` — дата создания или последнего изменения;
* `ETAG` — хэш;
* `STORAGE_CLASS` — [класс хранилища](storage-class.md);
* `IS_MULTIPART_UPLOADED` — маркер составной загрузки;
* `ENCRYPTION_STATUS` — статус [шифрования](encryption.md);
* `OBJECT_LOCK_RETAIN_UNTIL_DATE` — дата окончания [блокировки версии](object-lock.md);
* `OBJECT_LOCK_MODE` — тип блокировки версии;
* `OBJECT_LOCK_LEGAL_HOLD_STATUS` — статус бессрочной блокировки версии;
* `CHECKSUM_ALGORITHM` — алгоритм, используемый для расчета контрольной суммы;
* `OBJECT_ACCESS_CONTROL_LIST` — [ACL](acl.md) в кодировке base64;
* `OBJECT_OWNER` — идентификатор аккаунта владельца.

Актуальный перечень доступных параметров приведен в [Справочнике API](../api-ref/Bucket/createInventoryConfiguration.md).

## Результаты выгрузки {#results}

S3 Inventory генерирует манифест выгрузки, файл с контрольной суммой манифеста и отчет.

### Манифест {#manifest}

Манифест отчета представлен в двух файлах:

* `<префикс_выгрузки>/<имя_исходного_бакета>/<идентификатор_конфигурации>/<дата_выгрузки>/manifest.json` — файл манифеста;
* `<префикс_выгрузки>/<имя_исходного_бакета>/<идентификатор_конфигурации>/<дата_выгрузки>/manifest.checksum` — контрольная сумма манифеста, вычисленная по алгоритму [MD5](https://ru.wikipedia.org/wiki/MD5).

  Где:
  
  * `<префикс_выгрузки>` — префикс, по которому производилась выгрузка;
  * `<имя_исходного_бакета>` — имя бакета, из которого выгружаются метаданные;
  * `<идентификатор_конфигурации>` — идентификатор конфигурации выгрузки;
  * `<дата_выгрузки>` — дата выгрузки в формате `YYYY-MM-DDThh:mmZ`.

Манифест содержит следующую информацию об отчете:

* исходный бакет;
* целевой бакет;
* версия S3 Inventory;
* время начала сканирования бакета;
* формат файла;
* схема отчета — поля, которые попали в отчет;
* список файлов в отчете.

Пример манифеста:

```json
{
    "sourceBucket": "source-bucket",
    "destinationBucket": "example-inventory-destination-bucket",
    "version": "2016-11-30",
    "creationTimestamp" : "1514944800000",
    "fileFormat": "CSV",
    "fileSchema": "Bucket, Key, VersionId, IsLatest, IsDeleteMarker, Size",
    "files": [
        {
            "key": "prefix/source-bucket/config-name/data/3a6d560f-d5d5-434c-a896-15b13f52ac09.csv",
            "size": 2147483647,
            "MD5checksum": "f11166069f1990abeb9c97ace9cdfabc"
        }
    ]
}
```

### Отчет {#report}

Отчет представляет собой CSV-файл с метаданными всех объектов исходного бакета. Для выгрузки метаданных из крупных бакетов отчет может быть разбит на несколько файлов.

{% note info %}

Не гарантируется, что объекты в отчете будут отсортированы в каком-либо порядке.

{% endnote %}

Отчет генерируется по следующему пути: `<префикс_выгрузки>/<имя_исходного_бакета>/<идентификатор_конфигурации>/data/<имя_отчета>.csv`, где:

* `<префикс_выгрузки>` — префикс, по которому производилась выгрузка;
* `<имя_исходного_бакета>` — имя бакета, из которого выгружаются метаданные;
* `<идентификатор_конфигурации>` — идентификатор конфигурации выгрузки;
* `<имя_отчета>` — [UUID](https://ru.wikipedia.org/wiki/UUID) отчета, который можно найти в манифесте.

Пример отчета:

```text
source-bucket-name,some-file-key-1,16777216,2024-11-26 08:22:15.12345+00,STANDARD,75662d2b5026e477f88a1b385fccfad7,f,SSE-S3,,,,MD5,,ajegtlf2q28a********
source-bucket-name,some-file-key-2,647168,2025-05-25 22:05:28.12345+00,COLD,7f9429f312poga209cd412aae2020ae,f,SSE-S3,,,,MD5,,ajegtlf2q28a********
```

#### Полезные ссылки {#see-also}

* [Управление выгрузкой метаданных объектов (S3 Inventory) в бакете](../operations/buckets/manage-s3-inventory.md)
* [Скачивание объекта](../operations/objects/download.md)
* [Механизм логирования действий с бакетом](server-logs.md)