Go to file

Алексей Фетисов 000c1b1704 v1.0.1		10 months ago
config	v1.0.1	10 months ago
interfaces	v1.0.0	10 months ago
internal	v1.0.1	10 months ago
pkg	v1.0.1	10 months ago
samples	v1.0.0	10 months ago
.gitignore	v1.0.0	10 months ago
CHANGELOG.md	v1.0.1	10 months ago
README.md	v1.0.1	10 months ago
client.go	v1.0.1	10 months ago
go.mod	v1.0.1	10 months ago
go.sum	v1.0.0	10 months ago

README.md

Unescape Escape

Dynamix standard SDK

Dynamix standard SDK - это библиотека, написанная на языке GO, позволяющая взаимодействовать с API облачной платформы Vcontrol. Библиотека содержит в себе структуры и методы, необходимые для отправки запросов. Dynamix standard SDK имеет встроенный http-клиент и поддерживает разные способы авторизации на платформе. Библиотека так же содержит в себе модели ответов от платформы.

Установка

Выполните команду в терминале:

go get -u repository.basistech.ru/BASIS/dynamix-standard-go-sdk

Список API

Библиотека поддерживает одну группу API платформы:

api - группа, которая позволяет воспользоваться всем стандартным функционалом платформы;

API

Данная группа ручек позволяет выполнять следующие операции в платформе:

Cluster - управление списками кластеров
Extstorage - управление хранилищами для дисков ВМ;
Folder - управление списками логических папок;
Image - управление списками образов ВМ;
Node - управление списками хостов;
Respool - управление списками пулов ресурcов;
Tempate - управление шаблонами виртуальных машин;
VM - управление виртуальными машинами;

Работа с библиотекой

Алгоритм работы с библиотекой выглядит следующим образом:

Выполнение одного из действий:

настройка конфигурации клиента;
парсинг конфигурации из файла.

Создание клиента.
Создание структуры запроса.
Выполнение запроса.

Настройка конфигурации клиента

Сначала, необходимо создать переменную конфигурации клиента. Конфигурация состоит как из обязательных, так и необязательных полей.

Поле	Тип	Обязательный	Описание
Username	string	Да	username пользователя для выполнения запроса
Password	string	Да	password пользователя для выполнения запроса
VControlURL	string	Да	URL адрес платформы, с которой будет осуществляться взаимодействие
Retries	uint	Нет	Кол-во неудачных попыток выполнения запроса, по умолчанию - 5
Timeout	config.Duration	Нет	Таймаут HTTP клиента, по умолчанию - без ограничений
SSLSkipVerify	bool	Нет	Пропуск проверки подлинности сертификата
Token	string	Нет	JWT токен

Пример конфигурации клиента

import (
"repository.basistech.ru/BASIS/dynamix-standard-go-sdk/config"
)

func main(){
// Настройка конфигурации
cfg := config.Config{
    Username:      "<USERNAME>",
    Password:      "<PASSWORD>",
    VControlURL:   "<VCONTROL_URL>",
    Retries:       5,
    SSLSkipVerify: true,
}

cfg.SetTimeout(5 * time.Minute)
}

Парсинг конфигурации из файла

Также возможно создать переменную конфигурации из JSON или YAML файла, используя функцию ParseConfigJSON (или ParseConfigYAML) из пакета config.
См. пример файлов конфигурации ниже и в директории samples/.

import (
"repository.basistech.ru/BASIS/dynamix-standard-go-sdk/config"
)

func main() {
// Парсинг конфигурации из JSON-файла
cfg, _ := config.ParseConfigJSON("<PATH>")
}

Пример JSON конфигурации

{
	"username": "<USERNAME>",
	"password": "<PASSWORD>",
	"vControlURL": "<VCONTROL_URL>",
	"retries": 5,
	"timeout": "5m",
	"sslSkipVerify": false
}

Пример YAML конфигурации

username: <USERNAME>
password: <PASSWORD>
vControlURL: <VCONTROL_URL>
retries: 5
timeout: 5m
sslSkipVerify: false

Создание клиента

Создание клиента происходит с помощью функции-строителя New из основного пакета dynamix-standard-go-sdk, для избежания проблем с именами, пакету можно присвоить алиас vcontrol. Функция принимает конфигурацию, возвращает структуру VControlClient, с помощью которой можно взаимодействовать с платформой.

Пример

package main

import (
    vcontrol "repository.basistech.ru/BASIS/dynamix-standard-go-sdk"
    "repository.basistech.ru/BASIS/dynamix-standard-go-sdk/config"
)

func main() {
    // Настройка конфигурации
    cfg := config.Config{
        Username:      "<USERNAME>",
        Password:      "<PASSWORD>",
        VControlURL:   "<VCONTROL_URL>",
        Retries:       5,
    }

    cfg.SetTimeout(5*time.Minute)

    // Создание клиента
    client := vcontrol.New(cfg)
}

Создание структуры запроса

Структуры запросов определены в пакете pkg/:

В пакете находятся пакеты групп API:

api:
- pkg/cluster - для Cluster
- pkg/extstorage - для External storage
- pkg/folder - для Folrer
- pkg/image - для Image
- pkg/node - для Node
- pkg/respool - для Resourse pool
- pkg/tempalte - для Template
- pkg/vm - для VM

В каждом пакете находится пакет requests с структурами запросов

Все поля структуры имеют описание, в которых содержится:

Их назначение;
Обязательный или нет - поле required в комментариях;
Доп. информация (допустимые значения, значения по умолчанию).

Пример комментариев структуры

// ListImageRequest struct to get list of images
type ListImageRequest struct {
    // Name of image
    // Required: false
    Name string `url:"name,omitempty" json:"name,omitempty"`

    // Size of image
    // Required: false
    Size string `url:"size,omitempty" json:"size,omitempty"`

    // Type of image
    // Required: false
    ImageType string `url:"image_type,omitempty" json:"image_type,omitempty" validate:"omitempty,image_type"`

    // Status of image
    // Required: false
    Status string `url:"status,omitempty" json:"status,omitempty" validate:"omitempty,image_status"`

    // ShareID of image
    // Required: false
    ShareID string `url:"share_id,omitempty" json:"share_id,omitempty"`

    // Active if True Image is active
    // Required: false
    Active interface{} `url:"active,omitempty" json:"active,omitempty" validate:"omitempty,is_bool"`

    // IsTemplateImage If True Image is template
    // Required: false
    // Default: False
    IsTemplateImage bool `url:"is_template_image,omitempty" json:"is_template_image,omitempty"`

    // Mark of image
    // Required: false
    Mark string `url:"mark,omitempty" json:"mark,omitempty"`

    // image for filtering by text field
    // Required: false
    FilterText string `url:"filter_text,omitempty" json:"filter_text,omitempty"`

    // List columns which will be used by filter_text
    // Required: false
    FilterColumns string `url:"filter_columns,omitempty" json:"filter_columns,omitempty"`

    // List of columns for sorting.
    // Required: false
    Sort []string `url:"sort,omitempty" json:"sort,omitempty"`

    // Visibility status of the interface (visible, all, deleted).
    // Required: false
    Visibility string `url:"visibility,omitempty" json:"visibility,omitempty" validate:"omitempty,visibility"`

    // Filter VM Images that are unavailable now, because share is unavailable
    // Required: false
    HideUnavailable interface{} `url:"hide_unavailable,omitempty" json:"hide_unavailable,omitempty" validate:"omitempty,is_bool"`

    // Number of the page to return.
    // Required: false
    Page int `url:"page,omitempty" json:"page,omitempty"`

    // Number of items to return per page.
    // Required: false
    Limit int `url:"limit,omitempty" json:"limit,omitempty"`
}

Пример создания запроса для развертывания виртуальной машины:

package main

import (
    vcontrol "repository.basistech.ru/BASIS/dynamix-standard-go-sdk"
    "repository.basistech.ru/BASIS/dynamix-standard-go-sdk/config"
    vm "repository.basistech.ru/BASIS/dynamix-standard-go-sdk/pkg/vm/requests"
)

func main() {
    // Настройка конфигурации
    cfg := config.Config{
        Username:      "<USERNAME>",
        Password:      "<PASSWORD>",
        VControlURL:   "<VCONTROL_URL>",
        Retries:       5,
    }

    // Создание клиента
    client := vcontrol.New(cfg)

    // Создание структуры запроса
    // CreateRequest - реквест на создание виртуальной машины
    req := vm.CreateVMRequest{
        Name: "VMname",
        RAMSize: 1024,
        VideoRAMSize: 64
        CPUCount:     1,
        CPUSockets:   1,
    }
}

Выполнение запроса

Чтобы выполнить запрос, необходимо:

Вызвать у клиента метод, отвечающий за определение группы API для взаимодействия, на данный момент это .API(). Данный метод возвращает соответствующие структуры, с помощью которых можно совершать запросы.
Вызвать у возвращенной структуры метод, определяющий группу ручек для взаимодействия.

Доступные методы для .API():

.Cluster() - для работы с Cluster
.Extstorage() - для работы с External storage
.Folder() - для работы с Folder
.Image() - для работы с Image
.Node() - для работы с Node
.Respool() - для работы с Resource pool
.Template() - для работы с Template
.VM() - для работы с VM

Вызвать метод, отвечающий за выполнение запроса и передать в него:

контекст;
структуру запроса.

Обработать результат и ошибки.

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

    client.<API>.<группа>.<метод>

Пример выполнения запроса

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    vcontrol "repository.basistech.ru/BASIS/dynamix-standard-go-sdk"
    "repository.basistech.ru/BASIS/dynamix-standard-go-sdk/config"
    vm "repository.basistech.ru/BASIS/dynamix-standard-go-sdk/pkg/vm/requests"
    )

func main() {
    // Настройка конфигурации
    cfg := config.Config{
        Username:      "<USERNAME>",
        Password:      "<PASSWORD>",
        VControlURL:   "<VCONTROL_URL>",
        Retries:       5,
    }

    cfg.SetTimeout(5 * time.Minute)

    // Создание клиента
    client := vcontrol.New(cfg)

    // Создание структуры запроса
    req := vm.CreateVMRequest{
        Name:         "VMname",
        RAMSize:      1024,
        VideoRAMSize: 64,
        CPUCount:     1,
        CPUSockets:   1,
    }

    // Выполнение запроса с помощью конвейера
    res, err := client.API().VM().Create(context.Background(), req)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("%+v", res)
}

Для запросов Get и List реализованы запросы GetRaw и ListRaw, которые возвращают ответ не в виде соответствующей структуры, а в виде массива байт (JSON). Выполнение таких запросов происходит аналогично.

Пример выполнения GetRaw и ListRaw запросов

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    vcontrol "repository.basistech.ru/BASIS/dynamix-standard-go-sdk"
    "repository.basistech.ru/BASIS/dynamix-standard-go-sdk/config"
    vm "repository.basistech.ru/BASIS/dynamix-standard-go-sdk/pkg/vm/requests"
)

func main() {
    // Настройка конфигурации
    cfg := config.Config{
        Username:      "<USERNAME>",
        Password:      "<PASSWORD>",
        VControlURL:   "<VCONTROL_URL>",
        Retries:       5,
    }

    cfg.SetTimeout(5 * time.Minute)

    // Создание клиента
    client := vcontrol.New(cfg)

    // Создание структуры запроса
    // 1. Создание структуры запроса GetVMRequest на получение информации об виртуальной машине и выполнение GetRaw запроса с помощью конвейера
    req1 := vm.GetVMRequest{
        VmID:    360,
    }
    res1, err := client.API().VM().GetRaw(context.Background(), req1)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(res1))

    // 2. Создание структуры запроса ListVMRequest на получение информации об виртуальных машинах и выполнение ListRaw запроса с помощью конвейера
    req2 := vm.ListVMRequest{}
    res2, err := client.API().VM().ListRaw(context.Background(), req2)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(res2))
}

README.md Unescape Escape