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

# Копирование объектов

В Object Storage поддерживается копирование объектов на стороне сервера (_Server Side Copy_). 

Если в [бакете](../../concepts/bucket.md) отключено [шифрование](../../concepts/encryption.md), то [объекты](../../concepts/object.md) будут копироваться в бакеты на стороне сервера. Хост, на котором выполняется команда копирования, и Object Storage обмениваются только [ключами](../../concepts/object.md#key) объектов. Плата за трафик при копировании в таком случае не взимается, поскольку он является внутренним для объектного хранилища. При этом сами запросы на копирование [тарифицируются](../../pricing.md#prices-operations).

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

Большие объекты, загруженные с помощью [составной загрузки](../../concepts/multipart.md), хранятся в бакете частями. Копирование таких объектов происходит путем вызова [copyPart](../../s3/api-ref/multipart/copypart.md) для каждой его части. Таким образом, расходы при копировании составных объектов выше, чем при копировании обычных.

Вы можете скопировать как [все содержимое бакета](#copy-from-bucket-to-bucket), так и [отдельный его объект](#copy-single-object).


Чтобы работать с объектами в [зашифрованном](../../concepts/encryption.md) бакете, у пользователя или [сервисного аккаунта](../../../iam/concepts/users/service-accounts.md) вместе с [ролью](../../security/index.md#storage-configurer) `storage.configurer` должны быть следующие [роли на ключ шифрования](../../../kms/operations/key-access.md):

* `kms.keys.encrypter` — для чтения ключа, [шифрования](../../../kms/security/index.md#kms-keys-encrypter) и загрузки объектов;
* `kms.keys.decrypter` — для чтения ключа, [расшифровки](../../../kms/security/index.md#kms-keys-decrypter) и скачивания объектов;
* `kms.keys.encrypterDecrypter` — включает [разрешения](../../../kms/security/index.md#kms-keys-encrypterDecrypter), предоставляемые ролями `kms.keys.encrypter` и `kms.keys.decrypter`.

Подробнее смотрите [Сервисные роли Key Management Service](../../../kms/security/index.md#service-roles).


## Копирование одного объекта {#copy-single-object}

{% list tabs group=instructions %}

- Yandex Cloud CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

  1. Посмотрите описание команды CLI для копирования объекта:

      ```bash
      yc storage s3api copy-object --help
      ```

  1. Получите список бакетов в каталоге по умолчанию:
     
     ```bash
     yc storage bucket list
     ```
     
     Результат:
     
     ```text
     +------------------+----------------------+-------------+-----------------------+---------------------+
     |       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     | first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     ```
  1. Выполните команду:

      ```bash
      yc storage s3api copy-object \
        --copy-source <бакет_источник>/<ключ_объекта> \
        --bucket <бакет_приемник> \
        --key <ключ_объекта>
      ```

      Где:

      * `--copy-source` — имя бакета-источника и [ключ](../../concepts/object.md#key) объекта, который нужно скопировать.
      * `--bucket` — имя бакета, в который нужно скопировать объект.
      * `--key` — ключ, по которому объект будет храниться в бакете.

      Результат:

      ```bash
      copy_object_result:
        etag: '"d41d8cd98f00b204e9800998********"'
        last_modified_at: "2024-10-08T14:21:41.628Z"
      request_id: 61523025********
      copy_source_version_id: "null"
      ```

      Альтернативная команда:

      ```bash
      yc storage s3 cp \
        s3://<бакет_источник>/<ключ_объекта-оригинала> \
        s3://<бакет_приемник>/<ключ_объекта-копии>
      ```

      Результат:

      ```text
      copy: s3://my-bucket/object.txt to s3://new-bucket/object-copy.txt
      ```

      Подробнее о настройке команды в подразделе [Настройка параметров для команды yc storage s3 cp](#yc-s3-cp-config).

- AWS CLI {#aws-cli}

  1. Если у вас еще нет AWS CLI, [установите и сконфигурируйте его](../../tools/aws-cli.md).
  1. Выполните команду:

      ```bash
      aws --endpoint-url=https://storage.yandexcloud.kz/ \
        s3 cp s3://<бакет_источник>/<ключ_объекта> s3://<бакет_приемник>/<ключ_объекта>
      ```

      Где:

      * `--endpoint-url` — эндпоинт Object Storage.
      * `s3 cp` — команда для копирования объектов.

      Результат:

      ```text
      copy: s3://<бакет_источник>/<ключ_объекта> to s3://<бакет_приемник>/<ключ_объекта>
      ```

      Подробнее о команде `aws s3 cp` читайте в документации [AWS CLI Command Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/cp.html).

{% endlist %}

## Копирование нескольких объектов в другой бакет {#copy-from-bucket-to-bucket}

{% list tabs group=instructions %}

- Yandex Cloud CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

  1. Посмотрите описание команды CLI для копирования объектов:

      ```bash
      yc storage s3 cp --help
      ```

  1. Получите список бакетов в каталоге по умолчанию:
     
     ```bash
     yc storage bucket list
     ```
     
     Результат:
     
     ```text
     +------------------+----------------------+-------------+-----------------------+---------------------+
     |       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     | first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     ```
  1. Выполните команду:

      ```bash
      yc storage s3 cp \
        s3://<бакет_источник>/ \
        s3://<бакет_приемник>/ \
        --recursive \
        --exclude "*" \
        --include "*.txt"
      ```

      Где:
      * `--recursive` — копирует все объекты.
      * `--exclude` — исключает из копирования объекты, соответствующие шаблону. В примере исключает все объекты (`"*"`). Необязательный параметр.
      * `--include` — добавляет в копирование объекты, соответствующие шаблону. В примере добавляет только файлы с расширением `.txt`. Необязательный параметр.

      Параметры `--exclude` и `--include` применяются в порядке указания. Чтобы скопировать только объекты, соответствующие шаблону, сначала исключите все объекты с помощью `--exclude "*"`, затем добавьте нужные с помощью `--include`. Чтобы исключить объекты с определенным префиксом, используйте только `--exclude`, например `--exclude "prefix/*"`.

      Результат:

      ```text
      copy: s3://my-bucket/object-1.txt to s3://new-bucket/object-1-copy.txt
      copy: s3://my-bucket/object-2.txt to s3://new-bucket/object-2-copy.txt
      ...
      copy: s3://my-bucket/object-n.txt to s3://new-bucket/object-n-copy.txt
      ```

      Подробнее о настройке команды в подразделе [Настройка параметров для команды yc storage s3 cp](#yc-s3-cp-config).

- AWS CLI {#aws-cli}

  1. Если у вас еще нет AWS CLI, [установите и сконфигурируйте его](../../tools/aws-cli.md).
  1. Выполните команду:

      ```bash
      aws --endpoint-url=https://storage.yandexcloud.kz/ \
        s3 cp --recursive \
        --exclude "*" \
        --include "*.txt" \
        s3:<бакет_источник>/ s3:<бакет_приемник>/
      ```

      Где:

      * `--endpoint-url` — эндпоинт Object Storage.
      * `s3 cp` — команда для копирования объектов.
      * `--recursive` — копирует все объекты.
      * `--exclude` — исключает из копирования объекты, соответствующие шаблону. В примере исключает все объекты (`"*"`). Необязательный параметр.
      * `--include` — добавляет в копирование объекты, соответствующие шаблону. В примере добавляет только файлы с расширением `.txt`. Необязательный параметр.

      Параметры `--exclude` и `--include` применяются в порядке указания. Чтобы скопировать только объекты, соответствующие шаблону, сначала исключите все объекты с помощью `--exclude "*"`, затем добавьте нужные с помощью `--include`. Чтобы исключить объекты с определенным префиксом, используйте только `--exclude`, например `--exclude "prefix/*"`.

      Подробнее о команде `aws s3 cp` читайте в документации [AWS CLI Command Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/cp.html).

  {% note info %}

  Вы можете скопировать объекты между бакетами, как в рамках одного облака, так и между разными облаками. Для этого убедитесь, что у используемого [сервисного аккаунта](../../../iam/concepts/users/service-accounts.md) есть права на запись в оба бакета.

  {% endnote %}


{% endlist %}


## Настройка параметров для команды yc storage s3 cp {#yc-s3-cp-config}

{% list tabs group=instructions %}

- Yandex Cloud CLI {#cli}

  Вы можете настроить следующие параметры для команды `yc storage s3 cp`:
  
  * `s3.max-queue-size` — максимальное количество задач в очереди. Значение по умолчанию — `1000`.
  * `s3.max-concurrent-requests` — максимальное количество одновременных запросов. Значение по умолчанию — `10`.
  * `s3.multipart-threshold` — пороговый размер объекта, при превышении которого будет использоваться составная (multipart) загрузка. Значение по умолчанию — `8MB`.
  * `s3.multipart-chunksize` — размер частей, на которые будет делиться объект при составной (multipart) загрузке. Значение по умолчанию — `8MB`.
  
  Чтобы задать эти параметры, используйте команду `yc config set <параметр> <значение>`.

{% endlist %}

## Ошибки при загрузке {#errors}

При загрузке больших файлов с помощью Yandex Cloud CLI может возникнуть ошибка `fatal error: runtime: out of memory`. Объем памяти, необходимый для загрузки больших файлов, рассчитывается по формуле:

```text
s3.max-concurrent-requests × s3.multipart-chunksize
```

Где:

* `s3.max-concurrent-requests` — максимальное количество одновременных запросов. Значение по умолчанию — `10`.
* `s3.multipart-chunksize` — размер частей, на которые будет делиться объект при составной (multipart) загрузке. Значение по умолчанию — `8 MB`.

Подробнее о настройке команды в подразделе [Настройка параметров для команды yc storage s3 cp](#yc-s3-cp-config).