Общая информация

LinxCloud предоставляет RESTful XML API для программного управления хранимыми данными с помощью стандартных HTTP-запросов. API-интерфейс совместим с API-интерфейсом Amazon AWS S3, что позволяет взаимодействовать с сервисом, используя уже известные инструменты.

Протокол для сервиса AWS S3 (Simple Storage Service), созданный Amazon Web Services, является основным протоколом доступа к объектному хранилищу. S3 API — это команд, распознаваемые хранилищем, в ответ на которые выполняются определенные операции.

Команды объектному хранилищу можно передавать через клиент S3 CLI, инструкция по его установки описана в этой статье. Подробнее о клиенте можно узнать через ресурс официальной документации.

Инструкция по созданию или поиску API ключей.

API LinxCloud S3 создан для работы с API Amazon AWS S3. Установка «конечной точки» (endpoint) или «базового» (base) URL-адреса hb.bizmrg.com и создание ключевой пары LinxCloud S3 зачастую при использовании клиентской библиотеки позволит использовать сервис Объектного хранилища LinxCloud.

С LinxCloud S3 можно выполнять операции создания, чтения, обновления и удаления  бакетов и объектов и создавать списки управления доступом (ACL). Функции S3, которые поддерживаются и нет, указаны в таблице:

При использовании функции S3, которая не поддерживается LinxCloud, будет выведен S3-совместимый ответ об ошибке NotImplemented в формате XML.

Пример на Python

Пример с указанием учетных данных в параметрах создания сессии:

1\`\`\`
2import boto3
3session = boto3.session.Session()
4s3_client = session.client(
5    service_name = 's3',
6    endpoint_url = 'https://hb.bizmrg.com',
7    aws_access_key_id = 'YOUR_ACCESS_KEY',
8    aws_secret_access_key = 'YOUR_SECRET_KEY'
9)
10\`\`\`

Вариант с хранением учетных данных в файле.

Нужно создать файл ~/.aws/credentials в формате:

1\`\`\`console
2[default]
3aws_access_key_id = YOUR_ACCESS_KEY_ID
4aws_secret_access_key = YOUR_SECRET_ACCESS_KEY
5\`\`\`

Создаем сессию с указанием учетных данных в файле ~/.aws/credentials:

1\`\`\`
2import boto3
3session = boto3.session.Session()
4s3_client = session.client(
5    service_name='s3',
6    endpoint_url='https://hb.bizmrg.com'
7)
8\`\`\`

1#!/usr/bin/env python3
2import boto3
3from botocore.client import Config
4
5# Инициализировать сессию к Linx S3.
6session = boto3.session.Session()
7client = session.client('s3',
8                        region_name='ru-msk',
9                        endpoint_url='https://hb.bizmrg.com',
10                        aws_access_key_id='urvt4LXPwoSL9s6ieGTLT5',
11                        aws_secret_access_key='5JogfQUsWzzBE9xG1mbBkMkgW7pxY4TGyHgefSC9n2Xx')
12
13# Создать новый бакет.
14client.create_bucket(Bucket='my-test-bucket1')
15
16# Просмотреть список бакетов в проекте.
17response = client.list_buckets()
18buckets = [bucket['Name'] for bucket in response['Buckets']]
19print("Bucket List: %s" % buckets)

Пример на Go

1package main
2
3import (
4    "context"
5    "fmt"
6    "log"
7    "os"
8
9    "github.com/minio/minio-go"
10    "github.com/minio/minio-go/pkg/credentials"
11)
12
13func main() {
14    accessKey := os.Getenv("Linx Cloud_KEY")
15    secKey := os.Getenv("Linx Cloud_SECRET")
16    endpoint := "hb.bizmrg.com"
17    bucketName := "my-test-bucket1" // Названия бакетов должны быть уникальными для всех проектов Linx Cloud
18    ssl := true
19
20    if accessKey == "" || secKey == "" {
21        log.Fatal("Must provide Linx Cloud_KEY and Linx Cloud_SECRET environment variables!")
22    }
23
24    // Подключиться к Linx S3.
25    client, err := minio.New(endpoint, &minio.Options{
26        Creds:  credentials.NewStaticV4(accessKey, secKey, ""),
27        Secure: ssl,
28    })
29    if err != nil {
30        log.Fatal(err)
31    }
32
33    // Создать новый бакет.
34    err = client.MakeBucket(context.TODO(), bucketName, minio.MakeBucketOptions{Region: "ru-msk"})
35    if err != nil {
36        log.Fatal(err)
37    }
38
39    // Показать список всех бакетов.
40    buckets, err := client.ListBuckets(context.TODO())
41    if err != nil {
42        log.Fatal(err)
43    }
44
45    fmt.Println("List of all buckets for this access key:")
46    for _, bucket := range buckets {
47        fmt.Println(bucket.Name)
48    }
49}

Запросы к API LinxCloud S3 должны быть с заголовками HTTP-Authorization. Для совместимости со старыми клиентами поддерживаются типы подписи AWS v4 и AWS v2, с использованием клиентскую библиотеку подписи будут созданы по умолчанию.

Чтобы создать ключ доступа и секретный ключ следует зайти в меню «Аккаунты» сервиса «Объектное хранилище».

После создания аккаунта вы получите Access Key ID и Secret Key.

В таблице описана каждая часть подписи v4:

Пример заголовка авторизации

Authorization: AWS4-HMAC-SHA256
Credential=urvt4LXPwoSL9s6ieGTLT5/20200831/ru-msk/s3/aws4_request,
SignedHeaders=host;x-amz-acl;x-amz-content-sha256;x-amz-date,
Signature=6cab03bef74a80a0441ab7fd33c829a2cdb46bba07e82da518cdb78ac238fda5

Пример подписи (псевдо-код)

canonicalRequest = \`
${HTTPMethod}\n
${canonicalURI}\n
${canonicalQueryString}\n
${canonicalHeaders}\n
${signedHeaders}\n
${hashedPayload}
\`
stringToSign = "AWS4-HMAC-SHA256" + "\n" +
    date(format=ISO08601) + "\n" +
    date(format=YYYYMMDD) + "/" + "ru-msk" + "/" + "s3/aws4_request" + "\n" +
    Hex(SHA256Hash(canonicalRequest))
dateKey = HMAC-SHA256("AWS4" + ${SECRET_KEY}, date(format=YYYYMMDD))
dateRegionKey = HMAC-SHA256(dateKey, "ru-msk")
dateRegionServiceKey = HMAC-SHA256(dateRegionKey, "s3")
signingKey = HMAC-SHA256(dateRegionServiceKey, "aws4_request")
signature = Hex(HMAC-SHA256(signingKey, stringToSign))

Части, из которых состоит канонический запрос подписи:

• Используемый метод HTTP-запроса.
• Компонент пути URI запроса.
• Параметры строки запроса, включенный в запрос.
• Список заголовков запроса и их значений, разделенных новой строкой, в нижнем регистре и без пробелов.
• Список имен заголовков без значений, отсортированных по алфавиту, в нижнем регистре и через точку с запятой.
• Хэш SHA256 тела запроса.

Для такого запроса:

GET /?acl HTTP/1.1
Host: my-test-bucket1.hb.bizmrg.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20200831T221549Z

Канонический запрос будет иметь вид:

GET
/
acl=
host:my-test-bucket1.hb.bizmrg.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20200831T221549Z
host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

В таблице представлены общие заголовки, которые могут быть использованы в большинстве запросов:

А это общие заголовки, которые могут быть получены в большинстве ответов: