[Документация Yandex Cloud](../../index.md) > [Yandex Object Storage](../index.md) > [Концепции](index.md) > Объект

# Объект

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

Идентификатор объекта — строковый [ключ](#key).

Вместе с объектом Object Storage хранит [пользовательские](#user-meta) и [системные](#system-meta) метаданные.

Object Storage позволяет сохранять объекты в хранилищах разных классов в зависимости от ваших требований к длительности хранения и частоте операций с объектами. Подробнее читайте в разделе [Класс хранилища](storage-class.md).

Object Storage поддерживает следующие операции с объектами:

* Загрузка объекта в хранилище.
* Скачивание объекта из хранилища.
* Копирование объекта внутри хранилища, например, из бакета в бакет.
* Удаление объекта.
* [Частичное изменение объекта](object-patch.md) в хранилище.

Все остальные операции, которые можно выполнить с помощью [инструментов](../tools/index.md), являются комбинациями из указанных выше.

Для объектов в бакете можно настраивать [жизненные циклы](lifecycles.md).

Object Storage накладывает ограничения на размеры объектов и их метаданных. Подробнее смотрите в разделе [Квоты и лимиты в Object Storage](limits.md).

## Ключ {#key}

Ключ — это идентификатор объекта в бакете.

Структура хранения объектов плоская, хотя [инструменты](../tools/index.md) с графическим интерфейсом предлагают работать с Object Storage как с иерархической файловой системой. Видимость иерархического хранилища достигается за счет того, что ключи можно записывать как пути в файловой системе, например, `top_level_prefix/subprefix/text_data.txt`. В консоли управления Yandex Cloud префиксы называются папками.

Требования к ключу:
* кодировка UTF-8;
* размер меньше 1024 байт.

Используемые символы:

#|
|| **Категория** | **Перечень** | **Комментарий** ||
|| Оптимальные | `[a-zA-Z0-9]`, `!`, `-`, `_`, `.`, `*`, `'`, `(`, `)` | Эти символы, как правило, безопасно использовать. ||
|| Может потребоваться специальная обработка | `&`, `$`, `@`,`=`, `;`, `:`, `/`, `+`, `,`, `?`, пробелы и [управляющие ASCII-символы](https://ru.wikipedia.org/wiki/Управляющие_символы) с кодами `0`-`31` и `127` | Эти символы должны быть закодированы для URL или указаны в шестнадцатеричном виде (HEX). Некоторые из них являются непечатными, и браузер может их не поддерживать, поэтому они также требуют специальной обработки. ||
|| Не рекомендованные | `\`, `{`, `}`, `^`, ``` ` ```, `%`, `[`, `]`, `"`, `<`, `>`, `~`, ```|```, `#` и символы расширенной таблицы [ASCII-символов](https://ru.wikipedia.org/wiki/ASCII) с кодами `128`-`255` | Для этих символов необходима существенная специальная обработка, которая может отличаться в зависимости от используемого программного обеспечения. ||
|#

Подробнее о ключах в AWS S3 API смотрите на странице [Naming Amazon S3 objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html).

### Папка {#folder}

В Object Storage нет папок, однако графические файловые менеджеры, например, [CyberDuck](../tools/cyberduck.md) или интерфейс Object Storage в консоли управления Yandex Cloud имитируют папки. В роли папки выступает объект с нулевым размером, ключ которого входит в ключи других объектов как префикс. Например, объект с ключом `x` и размером 0 в консоли управления будет папкой, а объект с ключом `x/y.txt` — объектом `y.txt`, лежащим в папке `x`.

Каждый из [инструментов](../tools/index.md) управляет объектами и папками согласно своей логике, которая описана в документации на каждый из них.

{% note info %}

Удаление папки с объектами — асинхронная операция. В начале операции Object Storage готовит список объектов для удаления, затем удаляет их. Если в процессе удаления в Object Storage загрузить объект, который должен лежать в той папке, которая удаляется в текущий момент времени, то объект успешно загрузится. После завершения обеих операций в Object Storage останется папка, которая должна была быть удалена, с новым загруженным объектом.

{% endnote %}

## URL объекта {#object-url}

Ссылку на объект в бакете можно указывать в одном из форматов:
- Для бакета с публичным доступом:
  - `http(s)://<бакет>.storage.yandexcloud.kz/<ключ>`
  - `https://storage.yandexcloud.kz/<бакет>/<ключ>`
- Для бакета с ограниченным доступом:
  - `http(s)://<бакет>.storage.yandexcloud.kz/<ключ>?<параметры>`
  - `https://storage.yandexcloud.kz/<бакет>/<ключ>?<параметры>`

Где:

* `<бакет>` — имя бакета.
* `<ключ>` — [ключ](#key) (путь к файлу).
* `<параметры>` — дополнительные параметры, необходимые для доступа к бакету с ограниченным доступом. Например подпись и срок действия.

Из бакета с публичным доступом файлы можно получить по публичной ссылке как по протоколу HTTP, так и по протоколу HTTPS, даже если для бакета не [настроен](../operations/hosting/setup.md) хостинг сайта. В этом случае для доступа по протоколу HTTPS будет использован сертификат от [GlobalSign](https://www.globalsign.com/ru-ru) на уровне облака.

Для бакета с ограниченным доступом сервис генерирует временную подписанную ссылку, которая позволяет скачать объект даже из бакета с ограниченным доступом. [Подробнее про подписанные ссылки, их генерацию и использование](pre-signed-urls.md).


{% note info %}

При использовании URL в формате `http(s)://<имя_бакета>.storage.yandexcloud.kz` протокол HTTPS доступен для бакета только в том случае, если имя бакета не содержит точек. Например:

* `https://example.storage.yandexcloud.kz` — для этого бакета протокол HTTPS доступен.
* `http://example.ru.storage.yandexcloud.kz` — для этого бакета HTTPS недоступен.

Это связано с тем, что в Object Storage используются [сертификаты Wildcard](https://en.wikipedia.org/wiki/Wildcard_certificate), которые поддерживают только один уровень поддоменов.

Чтобы поддержать для бакета с точкой в имени протокол HTTPS, [загрузите собственный сертификат безопасности](../operations/hosting/certificate.md) в Object Storage.

{% endnote %}


{% note info %}

Если вы используете [AWS SDK для .NET](../tools/aws-sdk-net.md), обращайтесь к хосту `s3.yandexcloud.kz`.

{% endnote %}

## Метаданные {#metadata}

С объектом хранятся метаданные в виде пар `ключ-значение`. Они могут быть системными и пользовательскими.

Метаданные можно использовать для [поиска](../operations/objects/object-meta.md#tags-searching) объектов.

### Системные метаданные {#system-meta}

Системные метаданные определяются Object Storage.

Ключ | Описание
----- | -----
`Date` | Дата и время отправки запроса на загрузку объекта в Object Storage.
`Content-Length` | Размер объекта в байтах.
`Last-Modified` | Дата создания или последнего изменения объекта.
`Content-MD5` | MD5-хеш объекта, закодированный в base64.
`Cache-Control` | Значение HTTP заголовка `Cache-Control`, который клиент передает при сохранении объекта в бакет. В дальнейшем, Object Storage возвращает этот заголовок клиентам при ответе на запрос объекта или его метаданных.<br/><br/>Например, заголовок `Cache-Control: max-age=200` обозначает, что объект устаревает через 200 секунд после того, как клиент получил его. Подробнее о заголовке читайте в [RFC 7234](https://tools.ietf.org/html/rfc7234#section-5.2).
`Expires` | Значение HTTP заголовка `Expires`, который клиент передает при сохранении объекта в бакет. В дальнейшем, Object Storage возвращает этот заголовок клиентам при ответе на запрос объекта или его метаданных.<br/><br/>Например, заголовок `Expires: Thu, 15 Apr 2020 20:00:00 GMT` обозначает, что объект устаревает 15 апреля 2020 года в 20:00:00 по Гринвичу. Подробнее о заголовке читайте в [RFC 7234](https://tools.ietf.org/html/rfc7234#section-5.3).

### Пользовательские метаданные {#user-meta}

При загрузке объекта в Object Storage, вместе с ним можно передать набор метаданных в виде пар `ключ-значение`.

В HTTP API, совместимом с Amazon S3, метаданные передаются в виде HTTP-заголовков. Имя заголовка должно начинаться с `X-Amz-Meta-`. При запросе объекта через HTTP API Object Storage возвращает метаданные в виде HTTP-заголовков с этим же префиксом.

Ключи метаданных должны состоять только из [ASCII-символов](https://ru.wikipedia.org/wiki/ASCII). Передаваемые заголовки будут преобразованы по правилу: `X-Amz-Meta-foo-bar_baz` → `X-Amz-Meta-Foo-Bar_baz`. Здесь `Foo-Bar_baz` – ключ метаданных, которые будут сохранены вместе с объектом.

{% note info %}

Заголовок PUT-запроса не должен превышать 8 КБ. Размер пользовательских метаданных в этом заголовке не должен превышать 2 КБ.

{% endnote %}

Подробнее в инструкции [Управление пользовательскими метаданными объекта](../operations/objects/object-meta.md).

## Условия записи (conditional writes) {#conditional-writes}

Чтобы избежать случайной перезаписи и конфликтов при одновременных загрузках, можно определить условия записи объектов. Условия задаются с помощью заголовков [S3 API](../s3/index.md):

* Для методов [upload](../s3/api-ref/object/upload.md) и [completeUpload](../s3/api-ref/multipart/completeupload.md):

    * `If-Match` — запись выполняется, только если по указанному ключу уже существует объект и его текущий `ETag` совпадает со значениями в заголовке.
    * `If-None-Match` — запись выполняется, только если по указанному ключу в бакете нет объекта с таким же именем.

* Для методов [copy](../s3/api-ref/object/copy.md) и [copyPart](../s3/api-ref/multipart/copypart.md):

    * `X-Amz-Copy-Source-If-Match` — запись выполняется, только если по указанному ключу уже существует объект и его текущий `ETag` совпадает со значениями в заголовке.
    * `X-Amz-Copy-Source-If-None-Match` — запись выполняется, только если по указанному ключу в бакете нет объекта с таким же именем.

Условия можно использовать при загрузке и составной загрузке объектов, копировании объектов целиком или по частям. Подробнее в инструкции [Условная загрузка объекта](../operations/objects/upload.md#conditional-writes).

Коды ответов:

* `404` (`Not Found`) — объект по ключу отсутствует. Только для `If-Match`.
* `409` (`Conflict`) — условие выполнено, но во время загрузки ключ был изменен другой операцией записи.
* `412` (`Precondition Failed`) — условие не выполнено.

Особенности [составной загрузки](../operations/objects/multipart-upload.md#conditional-writes):

* Инициация составной загрузки происходит без условий. Заголовки применяются на этапе `Complete Multipart Upload`.
* При получении кода ответа `409` необходимо самостоятельно [прервать](../operations/objects/deleting-multipart.md) текущую составную загрузку и начать новую.


    {% note warning %}

    Пока составная загрузка не прервана, загруженные части остаются в бакете и тарифицируются как [хранение данных](../pricing.md#prices-storage).

    {% endnote %}

Чтобы сделать проверку условий обязательной, используйте [политику доступа](policy.md#conditional-writes-policy). Смотрите [примеры правил](policy.md#conditional-writes-rules).


## Примеры использования {#examples}

* [Получение статистики запросов к объекту с использованием S3 Select](../tutorials/server-logs.md)
* [Получение статистики запросов к объектам Object Storage с использованием Yandex Query](../tutorials/server-logs-yq.md)
* [Автоматическое копирование объектов из одного бакета Object Storage в другой](../tutorials/bucket-to-bucket.md)

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

* [Обзор способов управления доступом в Object Storage](../security/overview.md)