Взаимодействие с хранилищем

Поддерживаемые методы API в Спектр S3

Следующие операции и методы REST Amazon S3 поддерживаются реализацией протокола Amazon S3 в продукте Спектр S3:

  • Операции с сервисами:

    • GET Service

  • Операции с корзинами:

    • DELETE/HEAD/PUT Bucket;

    • GET Bucket (вывод списка объектов);

    • GET/PUT Bucket acl;

    • GET Bucket location;

    • GET Bucket Object versions;

    • GET/PUT Bucket versioning;

    • GET/PUT Bucket Logging (кроме элемента запроса Target Grants);

    • вывод списка передач по частям.

  • Операции с объектами:

    • DELETE/GET/HEAD/POST/PUT Object;

    • удаление нескольких объектов;

    • PUT Object — копия;

    • GET/PUT Object acl;

    • удаление нескольких объектов;

    • прерывание передачи по частям;

    • завершение передачи по частям;

    • инициирование передачи по частям;

    • вывод списка частей;

    • передача части.

  • Поддерживаемые методы:

    • AbortMultipartUpload;

    • CompleteMultipartUpload;

    • CopyObject;

    • CreateBucket;

    • CreateMultipartUpload;

    • DeleteBucket;

    • DeleteBucketLifecycleConfiguration;

    • DeleteBucketPolicy;

    • DeleteBucketReplication;

    • DeleteBucketTagging;

    • DeleteBucketWebsite;

    • DeleteObject;

    • DeleteObjects;

    • DeleteObjectTagging;

    • GetBucketAcl;

    • GetBucketLifecycleConfiguration;

    • GetBucketLocation;

    • GetBucketLogging;

    • GetBucketPolicy;

    • GetBucketReplication;

    • GetBucketTagging;

    • GetBucketVersioning;

    • GetBucketWebsite;

    • GetObject;

    • GetObjectAcl;

    • GetObjectLegalHold;

    • GetObjectLockConfiguration;

    • GetObjectRetention;

    • GetObjectTagging;

    • HeadBucket;

    • HeadObject;

    • ListBuckets;

    • ListMultipartUploads;

    • ListObjects;

    • ListObjectsV2;

    • ListObjectVersions;

    • ListParts;

    • PutBucketAcl;

    • PutBucketLifecycleConfiguration;

    • PutBucketLogging;

    • PutBucketPolicy;

    • PutBucketReplication;

    • PutBucketTagging;

    • PutBucketVersioning;

    • PutBucketWebsite;

    • PutObject;

    • PutObjectAcl;

    • PutObjectLegalHold;

    • PutObjectLockConfiguration;

    • PutObjectRetention;

    • PutObjectTagging;

    • UploadPart.

Дополнительные сведения об операциях REST Amazon S3 см. в стандарте Amazon Simple Storage Service.

Дополнительные сведения о методах REST Amazon S3 см. в документации API REST Amazon S3.

Заголовки запросов S3

Следующие заголовки запросов REST Amazon S3 в настоящее время поддерживаются реализацией Спектр S3 протокола Amazon S3:

  • Authorization;

  • Content-Length;

  • Content-Type;

  • Content-MD5;

  • Date;

  • Host;

  • x-amz-content-sha256;

  • x-amz-date;

  • x-amz-security-token;

  • x-amz-storage-class;

  • x-amz-object-lock-retain-until-date;

  • x-amz-object-lock-mode;

  • x-amz-object-lock-legal-hold;

  • x-amz-bypass-governance-retention;

  • x-amz-bucket-object-lock-enabled;

  • x-amz-geo-endpoint;

  • x-amz-geo-access-key;

  • x-amz-geo-access-secret.

Следующие заголовки запросов REST Amazon S3 игнорируются:

  • Expect;

  • x-amz-security-token.

Дополнительные сведения о заголовках запросов REST Amazon S3 см. в документации API REST Amazon S3.

Поддерживаемые заголовки ответов S3

Следующие заголовки ответов REST Amazon S3 поддерживаются реализацией Спектр S3 протокола Amazon S3:

  • Content-Length;

  • Content-Type;

  • Connection;

  • Date;

  • ETag;

  • x-amz-delete-marker;

  • x-amz-request-id;

  • x-amz-version-id;

  • x-amz-object-lock-retain-until-date;

  • x-amz-object-lock-mode;

  • x-amz-object-lock-legal-hold;

  • x-amz-geo-endpoint;

  • x-amz-geo-access-key;

  • x-amz-geo-access-secret.

Следующие заголовки ответов REST Amazon S3 не используются:

  • Server;

  • x-amz-id-2.

Поддерживаемые заголовки ответов об ошибках S3

Следующие заголовки ответов об ошибках REST Amazon S3 поддерживаются реализацией Спектр S3 протокола Amazon S3:

  • Code;

  • Error;

  • Сообщение.

Следующие заголовки ответов об ошибках REST Amazon S3 не поддерживаются:

  • RequestId (не используется);

  • Ресурс.

Поддерживаемые заголовки ответов об ошибках S3

Реализация протокола Amazon S3 в Спектр S3 поддерживает следующие схемы проверки подлинности:

Реализация протокола Amazon S3 в Спектр S3 поддерживает следующие методы проверки подлинности:

Следующий способ проверки подлинности не поддерживается:

Функции Amazon S3, поддерживаемые политиками корзин S3

Реализация политик корзин Amazon S3 в продукте Спектр S3 поддерживает следующие действия S3, ключи условий и операторы условий:

  • s3:AbortMultipartUpload;

  • s3:ListMultipartUploadParts;

  • s3:DeleteObject;

  • s3:DeleteObjectVersion;

  • s3:GetObject;

  • s3:GetObjectAcl;

  • s3:GetObjectVersion;

  • s3:GetObjectVersionAcl;

  • s3:PutObject;

  • s3:PutObjectAcl;

  • s3:PutObjectVersionAcl;

  • s3:RestoreObject;

  • s3:DeleteObjectTagging;

  • s3:DeleteObjectVersionTagging;

  • s3:GetObjectLegalHold;

  • s3:GetObjectRetention;

  • s3:GetObjectTagging;

  • s3:GetObjectTorrent;

  • s3:GetObjectVersionTagging;

  • s3:PutObjectLegalHold;

  • s3:PutObjectRetention;

  • s3:PutObjectTagging;

  • s3:PutObjectVersionTagging.

Действия над корзинами:

  • s3:CreateBucket;

  • s3:DeleteBucket;

  • s3:ListBucket;

  • s3:ListBucketMultipartUploads;

  • s3:ListBucketVersions.

Действия над подресурсами корзин:

  • s3:DeleteBucketOwnershipControls;

  • s3:DeleteBucketPolicy;

  • s3:DeleteBucketWebsite;

  • s3:GetBucketAcl;

  • s3:GetBucketCORS;

  • s3:GetBucketLocation;

  • s3:GetBucketLogging;

  • s3:GetBucketNotification;

  • s3:GetBucketObjectLockConfiguration;

  • s3:GetBucketOwnershipControls;

  • s3:GetBucketPolicy;

  • s3:GetBucketPolicyStatus;

  • s3:GetBucketRequestPayment;

  • s3:GetBucketTagging;

  • s3:GetBucketVersioning;

  • s3:GetBucketWebsite;

  • s3:GetLifecycleConfiguration;

  • s3:GetReplicationConfiguration;

  • s3:ListAllMyBuckets;

  • s3:PutBucketAcl;

  • s3:PutBucketCORS;

  • s3:PutBucketLogging;

  • s3:PutBucketNotification;

  • s3:PutBucketObjectLockConfiguration;

  • s3:PutBucketOwnershipControls;

  • s3:PutBucketPolicy;

  • s3:PutBucketRequestPayment;

  • s3:PutBucketTagging;

  • s3:PutBucketVersioning;

  • s3:PutBucketWebsite;

  • s3:PutLifecycleConfiguration;

  • s3:PutReplicationConfiguration.

Поддерживаемые ключи условий:

  • aws:principaltype;

  • aws:securetransport;

  • aws:SourceIp;

  • aws:userid;

  • s3:authType;

  • s3:delimiter;

  • s3:existingobjecttag/…​;

  • s3:locationconstraint;

  • s3:max-keys;

  • s3:prefix;

  • s3:requestobjecttag/…​;

  • s3:signatureAge;

  • s3:signatureversion;

  • s3:TlsVersion;

  • s3:versionid;

  • s3:x-amz-acl;

  • s3:x-amz-content-sha256;

  • s3:x-amz-copy-source;

  • s3:x-amz-grant-full-control;

  • s3:x-amz-grant-read;

  • s3:x-amz-grant-read-acp;

  • s3:x-amz-grant-write;

  • s3:x-amz-grant-write-acp;

  • s3:x-amz-metadata-directive;

  • s3:x-amz-storage-class.

Поддерживаемые операторы условий:

  • BinaryEquals;

  • Bool;

  • DateEquals;

  • DateGreaterThan;

  • DateGreaterThanEquals;

  • DateLessThan;

  • DateLessThanEquals;

  • DateNotEquals;

  • IpAddress;

  • NotIpAddress;

  • Null;

  • NumericEquals;

  • NumericGreaterThan;

  • NumericGreaterThanEquals;

  • NumericLessThan;

  • NumericLessThanEquals;

  • NumericNotEquals;

  • StringEquals;

  • StringEqualsIgnoreCase;

  • StringLike;

  • StringNotEquals;

  • StringNotEqualsIgnoreCase;

  • StringNotLike.

Доступ к S3 хранилищу с помощью Cyberduck

Чтобы получить доступ к Спектр S3 с помощью CyberDuck, необходимо:

  1. В CybetDuck нажать кнопку Открыть подключение.

    1. Указать учётные данные для подключения:

      • Доменное имя оконечной точки S3.

      • Идентификатор ключа доступа.

      • Пароль, секретный ключ доступа пользователя к хранилищу объектов.

        image$cyberduck login

        По умолчанию подключение устанавливается через протокол HTTPS. Чтобы использовать CyberDuck поверх HTTP, необходимо установить специальный профиль S3.

  2. Нажать кнопку Connect.

  3. Когда подключение будет установлено, выбрать в главном меню Файл  Создать папку, чтобы создать корзину.

    image$create new folder

    1. Ввести название новой корзины и нажать кнопку Create.

      Необходимо использовать названия корзин, соответствующие соглашениям об именовании DNS.

      Новая корзина появится в хранилище и отобразится в CyberDuck.

Управление версиями корзин в S3

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

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

Управление версиями корзин по умолчанию отключено. В CyberDuck его можно включить в свойствах корзины, как показано на рисунке.

image$turn on versioning

Правила именования корзин S3

Рекомендуется использовать имена корзин, соответствующие соглашениям об именовании DNS:

  • должно содержать от 3 (минимум) до 63 (максимум) символов;

  • состоит только из строчных букв латинского алфавита, цифр, точек . и дефисов -;

  • начинается и заканчивается буквой или цифрой;

  • не содержать две смежные точки;

  • не отформатирован как IP-адрес (например, 192.168.5.4);

  • не начинается с префикса xn--;

  • не заканчивается суффиксом -s3alias;

  • не заканчивается суффиксом --ol-s3;

  • является уникальным для выбранного тенанта.

Примеры использования API S3 через AWS CLI

AbortMultipartUpload

Эта команда отменяет многократную загрузку в S3.

aws s3api abort-multipart-upload \
    --bucket ваш-бакет \
    --key ваш-объект \
    --upload-id <id-загрузки>

CompleteMultipartUpload

Эта команда завершает многократную загрузку в S3.

aws s3api complete-multipart-upload \
    --bucket <bucket> \
    --key <object> \
    --upload-id <id-загрузки> \
    --multipart-upload file://parts.json

CopyObject

Эта команда копирует объект из одного места в другое:

aws s3api copy-object \
    --copy-source <source-bucket>/<target-bucket> \
    --bucket <target-bucket> \
    --key <object>

CreateBucket

Эта команда создаёт новый бакет в S3:

aws s3api create-bucket \
    --bucket <new-bucket-name> \
    --region us-east-1

CreateMultipartUpload

Эта команда инициирует многократную загрузку в S3:

aws s3api create-multipart-upload \
    --bucket <bucket> \
    --key <object>

DeleteBucket

Эта команда удаляет S3-бакет:

aws s3api delete-bucket \
    --bucket <bucket>

DeleteBucketLifecycleConfiguration

Эта команда удаляет конфигурацию жизненного цикла для бакета:

aws s3api delete-bucket-lifecycle \
    --bucket <bucket>

DeleteBucketPolicy

Эта команда удаляет политику доступа для бакета:

aws s3api delete-bucket-policy \
    --bucket <bucket>

DeleteBucketReplication

Эта команда удаляет конфигурацию репликации для бакета:

aws s3api delete-bucket-replication \
    --bucket <bucket>

DeleteBucketTagging

Эта команда удаляет теги для бакета:

aws s3api delete-bucket-tagging \
    --bucket <bucket>

DeleteBucketWebsite

Эта команда удаляет конфигурацию веб-сайта для бакета:

aws s3api delete-bucket-website \
    --bucket <bucket>

DeleteObject

Эта команда удаляет объект из S3-бакета:

aws s3api delete-object \
    --bucket <bucket> \
    --key <object>

DeleteObjects

Эта команда удаляет несколько объектов из S3-бакета:

aws s3api delete-objects \
    --bucket <bucket> \
    --delete file://deleteobjects.json

Пример содержимого файла deleteobjects.json:

{
  "Objects": [
    { "Key": "ваш-объект-1" },
    { "Key": "ваш-объект-2" }
  ]
}

DeleteObjectTagging

Эта команда удаляет теги для объекта в S3:

aws s3api delete-object-tagging \
    --bucket <bucket> \
    --key <object>

GetBucketAcl

Эта команда получает список правил доступа (ACL) для бакета:

aws s3api get-bucket-acl \
    --bucket <bucket>

GetBucketLifecycleConfiguration

Эта команда получает конфигурацию жизненного цикла для бакета:

aws s3api get-bucket-lifecycle-configuration \
    --bucket <bucket>

GetBucketLocation

Эта команда получает местоположение бакета:

aws s3api get-bucket-location \
    --bucket <bucket>

GetBucketLogging

Эта команда получает конфигурацию ведения журнала для бакета:

aws s3api get-bucket-logging \
    --bucket <bucket>

GetBucketPolicy

Эта команда получает политику доступа для бакета:

aws s3api get-bucket-policy \
    --bucket <bucket>

GetBucketReplication

Эта команда получает конфигурацию репликации для бакета:

aws s3api get-bucket-replication \
    --bucket <bucket>

GetBucketTagging

Эта команда получает теги для бакета:

aws s3api get-bucket-tagging \
    --bucket <bucket>

GetBucketVersioning

Эта команда получает конфигурацию версионности для бакета:

aws s3api get-bucket-versioning \
    --bucket <bucket>

GetBucketWebsite

Эта команда получает конфигурацию веб-сайта для бакета:

aws s3api get-bucket-website \
    --bucket <bucket>

GetObject

Эта команда получает объект из S3-бакета и сохраняет в указанное расположение:

aws s3api get-object \
    --bucket <bucket> \
    --key <object> \
    /path/to/save/place

GetObjectAcl

Эта команда получает список правил доступа (ACL) для объекта S3:

aws s3api get-object-acl \
    --bucket <bucket> \
    --key <object>

GetObjectLegalHold

Эта команда получает состояние правового удержания для объекта в S3:

aws s3api get-object-legal-hold \
    --bucket <bucket> \
    --key <object>

GetObjectLockConfiguration

Эта команда получает конфигурацию блокировки объекта S3:

aws s3api get-object-lock-configuration \
    --bucket <bucket>

GetObjectRetention

Эта команда получает конфигурацию удержания объекта в S3:

aws s3api get-object-retention \
    --bucket <bucket> \
    --key <object>

GetObjectTagging

Эта команда получает теги для объекта в S3:

aws s3api get-object-tagging \
    --bucket <bucket> \
    --key <object>

HeadBucket

Эта команда получает метаданные для указанного S3-бакета:

aws s3api head-bucket \
    --bucket <bucket>

HeadObject

Эта команда получает метаданные для объекта в S3:

aws s3api head-object \
    --bucket <bucket> \
    --key <object>

ListBuckets

Эта команда получает список всех S3-бакетов в вашем аккаунте AWS:

aws s3api list-buckets

ListMultipartUploads

Эта команда получает список всех незавершенных многократных загрузок в S3:

aws s3api list-multipart-uploads \
    --bucket <bucket>

ListObjects

Эта команда получает список объектов в S3-бакете (старый способ):

aws s3api list-objects \
    --bucket <bucket>

ListObjectsV2

Эта команда получает список объектов в S3-бакете (новый способ):

aws s3api list-objects-v2 \
    --bucket <bucket>

ListObjectVersions

Эта команда получает список версий объектов в S3-бакете:

aws s3api list-object-versions \
    --bucket <bucket>

ListParts

Эта команда получает список частей, загруженных для многократной загрузки объекта:

aws s3api list-parts \
    --bucket <bucket> \
    --key <object> \
    --upload-id <upload-id>

PutBucketAcl

Эта команда устанавливает правила доступа (ACL) для S3-бакета:

aws s3api put-bucket-acl \
    --bucket <bucket> \
    --acl private

PutBucketLifecycleConfiguration

Эта команда устанавливает конфигурацию жизненного цикла для S3-бакета:

aws s3api put-bucket-lifecycle-configuration \
    --bucket <bucket> \
    --lifecycle-configuration file://lifecycle.json

Пример заполнения файла lifecycle.json:

{
  "Rules": [
    {
      "ID": "ExpireRule",
      "Status": "Enabled",
      "Filter": {},
      "Expiration": {
        "Days": 30
      }
    }
  ]
}

PutBucketLogging

Эта команда включает или настраивает ведение журнала для S3-бакета:

aws s3api put-bucket-logging \
    --bucket <bucket> \
    --logging-status file://logging.json

Пример заполнения файла logging.json:

{
  "LoggingEnabled": {
    "TargetBucket": "your-log-bucket",
    "TargetPrefix": "log/"
  }
}

PutBucketPolicy

Эта команда устанавливает политику доступа для S3-бакета:

aws s3api put-bucket-policy \
    --bucket <bucket> \
    --policy file://bucket-policy.json

Пример заполнения файла bucket-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

PutBucketReplication

Эта команда устанавливает конфигурацию репликации для S3-бакета:

aws s3api put-bucket-replication \
    --bucket <bucket> \
    --replication-configuration file://replication.json

Пример заполнения файла replication.json:

{
  "Role": "arn:aws:iam::your-account-id:role/replication-role",
  "Rules": [
    {
      "Status": "Enabled",
      "Prefix": "",
      "Destination": {
        "Bucket": "arn:aws:s3:::destination-bucket"
      }
    }
  ]
}
----

PutBucketTagging

Эта команда устанавливает теги для S3-бакета:

aws s3api put-bucket-tagging \
    --bucket <bucket> \
    --tagging 'TagSet=[{Key=Environment,Value=Production}]'

PutBucketVersioning

Эта команда включает или отключает версионность объектов в S3-бакете:

aws s3api put-bucket-versioning \
    --bucket <bucket> \
    --versioning-configuration Status=<status>

Здесь <status> — значение Enabled (версионность включена) или Disabled (версионность выключена).

PutBucketWebsite

Эта команда устанавливает конфигурацию веб-сайта для S3-бакета:

aws s3api put-bucket-website \
    --bucket <bucket> \
    --website-configuration file://website.json

Пример заполнения файла website.json:

{
  "IndexDocument": {
    "Suffix": "index.html"
  },
  "ErrorDocument": {
    "Key": "error.html"
  }
}
----

PutObject

Эта команда загружает объект в S3-бакет:

aws s3api put-object \
    --bucket <bucket> \
    --key <object> \
    --body /path/to/local/file

PutObjectAcl

Эта команда устанавливает правила доступа (ACL) для объекта в S3:

aws s3api put-object-acl \
    --bucket <bucket> \
    --key <object> \
    --acl public-read

PutObjectLegalHold

Эта команда устанавливает правовое удержание для объекта в S3:

aws s3api put-object-legal-hold \
    --bucket <bucket> \
    --key <object> \
    --legal-hold Status=ON

PutObjectLockConfiguration

Эта команда устанавливает конфигурацию блокировки для объекта в S3:

aws s3api put-object-lock-configuration \
    --bucket <bucket> \
    --object-lock-configuration file://lock-config.json

Пример заполнения файла lock-config.json:

{
  "ObjectLockConfiguration": {
    "LockConfiguration": {
      "Status": "Enabled",
      "ObjectLockRule": {
        "DefaultRetention": {
          "Mode": "GOVERNANCE",
          "Days": 30
        }
      }
    }
  }
}
----

PutObjectRetention

Эта команда устанавливает конфигурацию удержания для объекта в S3:

aws s3api put-object-retention \
    --bucket <bucket> \
    --key <object> \
    --retention Retention={"Mode":"GOVERNANCE","Date":"2023-12-31T00:00:00Z"}

PutObjectTagging

Эта команда устанавливает теги для объекта в S3:

aws s3api put-object-tagging \
    --bucket <bucket> \
    --key <object> \
    --tagging 'TagSet=[{Key=Key1,Value=Value1},{Key=Key2,Value=Value2}]'

UploadPart

Эта команда загружает часть объекта при многократной загрузке:

aws s3api upload-part \
    --bucket