Аутентификация в API Object Storage
Вы можете работать с Object Storage с помощью следующих типов API:
AWS S3 API
Для аутентификации в AWS S3 API и работы с Terraform и другими поддерживаемыми инструментами используйте статический ключ доступа. Статический ключ доступа выпускается на сервисный аккаунт, и все действия с использованием этого ключа выполняются от имени этого сервисного аккаунта. Подробнее см. Как пользоваться S3 API.
Статический ключ для доступа к Object Storage можно безопасно хранить в сервисе Yandex Lockbox. Подробнее см. Использование секрета Yandex Lockbox для хранения статического ключа доступа.
Полный перечень методов S3 API см. в Справочнике S3 API.
Примечание
Сервисный аккаунт может просматривать список бакетов только в том каталоге, в котором он был создан.
Сервисный аккаунт может выполнять действия с объектами в бакетах, которые созданы в каталогах, отличных от каталога сервисного аккаунта. Для этого назначьте сервисному аккаунту роли на нужный каталог или бакет в нем.
Если вы хотите использовать AWS S3 API напрямую, без SDK и приложений, вам придется самостоятельно подписывать запросы. Процесс формирования запроса и подписи вы можете отработать с помощью AWS CLI в режиме отладки.
Пример использования AWS S3 API
Начиная с версии 8.3.0 утилита curl поддерживает автоматическое формирование строки для подписи, подпись запроса и подстановку необходимых заголовков при работе с AWS S3 API.
Также вы можете вручную сформировать указанные заголовки и подписать запрос. См. пример для Версии curl 8.2.1 и ниже.
Примечание
Убедитесь, что сервисный аккаунт, от имени которого вы выполняете запрос, имеет необходимые права для выполнения запрашиваемого действия. Например, для загрузки объекта в бакет назначьте сервисному аккаунту роль storage.uploader на бакет. Подробнее см. Обзор способов управления доступом в Object Storage.
Ниже приведены примеры запросов для загрузки объекта в бакет.
AWS_KEY_ID="<идентификатор_статического_ключа>"
AWS_SECRET_KEY="<секретный_ключ>"
LOCAL_FILE="<путь_к_локальному_файлу>"
BUCKET_NAME="<имя_бакета>"
OBJECT_PATH="<ключ_объекта>"
curl \
--request PUT \
--user "${AWS_KEY_ID}:${AWS_SECRET_KEY}" \
--aws-sigv4 "aws:amz:ru-central1:s3" \
--upload-file "${LOCAL_FILE}" \
--verbose \
"https://storage.yandexcloud.kz/${BUCKET_NAME}/${OBJECT_PATH}"
Где:
AWS_KEY_ID— идентификатор статического ключа доступа.AWS_SECRET_KEY— секретный ключ.LOCAL_FILE— путь к локальному файлу, который вы хотите загрузить, например./sample.txt.BUCKET_NAME— имя бакета, в который загружается файл.OBJECT_PATH— ключ, который будет присвоен объекту в бакете, напримерnew-prefix/sample-object.txt.
Аналогично вы можете загрузить файл в бакет, не сохраняя его локально. Например, заархивируйте директорию и отправьте архив в бакет:
AWS_KEY_ID="<идентификатор_статического_ключа>"
AWS_SECRET_KEY="<секретный_ключ>"
BUCKET_NAME="<имя_бакета>"
OBJECT_PATH="<ключ_объекта>"
DIRECTORY_PATH="<путь_к_директории>"
tar -cvzf - "${DIRECTORY_PATH}" | curl \
--request PUT \
--user "${AWS_KEY_ID}:${AWS_SECRET_KEY}" \
--aws-sigv4 "aws:amz:ru-central1:s3" \
--upload-file - \
--verbose \
"https://storage.yandexcloud.kz/${BUCKET_NAME}/${OBJECT_PATH}"
Где DIRECTORY_PATH — путь к директории, которую вы хотите заархивировать.
AWS_KEY_ID="<идентификатор_статического_ключа>"
AWS_SECRET_KEY="<секретный_ключ>"
LOCAL_FILE="<путь_к_локальному_файлу>"
BUCKET_NAME="<имя_бакета>"
OBJECT_PATH="<ключ_объекта>"
CONTENT_TYPE="<MIME-тип_объекта>"
DATE_VALUE=`date -R`
STRING_TO_SIGN="PUT\n\n${CONTENT_TYPE}\n${DATE_VALUE}\n/${BUCKET_NAME}/${OBJECT_PATH}"
SIGNATURE=`echo -en ${STRING_TO_SIGN} | openssl sha1 -hmac ${AWS_SECRET_KEY} -binary | base64`
curl \
--request PUT \
--upload-file "${LOCAL_FILE}" \
--verbose \
--header "Host: storage.yandexcloud.kz" \
--header "Date: ${DATE_VALUE}" \
--header "Content-Type: ${CONTENT_TYPE}" \
--header "Authorization: AWS ${AWS_KEY_ID}:${SIGNATURE}" \
"https://storage.yandexcloud.kz/${BUCKET_NAME}/${OBJECT_PATH}"
Где:
AWS_KEY_ID— идентификатор статического ключа доступа.AWS_SECRET_KEY— секретный ключ.LOCAL_FILE— путь к локальному файлу, который вы хотите загрузить, например./sample.txt.BUCKET_NAME— имя бакета, в который загружается файл.OBJECT_PATH— ключ, который будет присвоен объекту в бакете, напримерnew-prefix/sample-object.txt.CONTENT_TYPE— MIME-тип загружаемого объекта, напримерtext/plain.
Yandex Cloud gRPC и REST API
Для аутентификации в Yandex Cloud gRPC и REST API получите IAM-токен. Подробнее о получении IAM-токена для разных типов аккаунтов:
Полученный IAM-токен указывайте при обращении к ресурсам Yandex Cloud через API. Передайте IAM-токен в заголовке Authorization в следующем формате:
Authorization: Bearer <IAM-токен>
Полный перечень вызовов и методов Yandex Cloud API смотрите в справочниках gRPC API и REST API.
Пример использования Yandex Cloud API
В примере создается бакет со стандартным классом хранилища и размером 50 ГБ.
export IAM_TOKEN="<IAM-токен>"
grpcurl \
-H "Authorization: Bearer $IAM_TOKEN" \
-d '{
"name": "<имя_бакета>",
"folder_id": "<идентификатор_каталога>",
"default_storage_class": "STANDARD",
"max_size": "53687091200",
"anonymous_access_flags": [{
"read": false,
"list": false,
"configRead": false
}]
}' \
storage.api.yandexcloud.kz:443 \
yandex.cloud.storage.v1.BucketService/Create
Где:
IAM_TOKEN— IAM-токен. Подробнее см. Получение IAM-токена.name— имя бакета.folder_id— идентификатор каталога.default_storage_class— класс хранилища.max_size— размер бакета.anonymous_access_flags— настройки доступа к бакету:read— публичный доступ на чтение объектов.list— публичный доступ к списку объектов.configRead— публичный доступ на чтение настроек.
Результат:
{
"id": "e3ehmmasama1********",
"description": "create bucket",
"createdAt": "2023-08-10T06:32:19.836842Z",
"createdBy": "ajego134p5h1********",
"modifiedAt": "2023-08-10T06:32:19.836842Z",
"done": true,
"metadata": {"@type":"type.googleapis.com/yandex.cloud.storage.v1.CreateBucketMetadata","name":"<имя_бакета>"},
"response": {"@type":"type.googleapis.com/yandex.cloud.storage.v1.Bucket","acl":{},"anonymousAccessFlags":{"read":false,"list":false},"createdAt":"2023-08-10T06:32:17.557756Z","defaultStorageClass":"STANDARD","folderId":"b1gmit33ngp3********","maxSize":"53687091200","name":"<имя_бакета>","versioning":"VERSIONING_DISABLED"}
}
export IAM_TOKEN="<IAM-токен>"
curl \
--request POST \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $IAM_TOKEN" \
--data '{
"name": "<имя_бакета>",
"folderId": "<идентификатор_каталога>",
"defaultStorageClass": "STANDARD",
"maxSize": "53687091200",
"anonymousAccessFlags": {
"read": false,
"list": false,
"configRead": false
}
}' \
https://storage.api.yandexcloud.kz/storage/v1/buckets
Где:
IAM_TOKEN— IAM-токен. Подробнее см. Получение IAM-токена.name— имя бакета.folderId— идентификатор каталога.default_storage_class— класс хранилища.maxSize— размер бакета.anonymousAccessFlags— настройки доступа к бакету:read— публичный доступ на чтение объектов.list— публичный доступ к списку объектов.configRead— публичный доступ на чтение настроек.
Результат:
{
"done": true,
"metadata": {
"@type": "type.googleapis.com/yandex.cloud.storage.v1.CreateBucketMetadata",
"name": "<имя_бакета>"
},
"response": {
"@type": "type.googleapis.com/yandex.cloud.storage.v1.Bucket",
"anonymousAccessFlags": {
"read": false,
"list": false
},
"acl": {},
"name": "<имя_бакета>",
"folderId": "b1gmit33ngp3********",
"defaultStorageClass": "STANDARD",
"versioning": "VERSIONING_DISABLED",
"maxSize": "53687091200",
"createdAt": "2023-08-08T12:54:29.321021Z"
},
"id": "e3enrkcct2pt********",
"description": "create bucket",
"createdAt": "2023-08-08T12:54:32.111022Z",
"createdBy": "ajego134p5h1********",
"modifiedAt": "2023-08-08T12:54:32.111022Z"
}