REST API

Взаимодействие с облачным сервисом вычислений ArhiCloud осуществляется через эндпоинты. Для аутентификации используется лицензионный ключ. Доступ предоставляется автоматически при создании API-ключа в личном кабинете.

Получение лицензионного ключа

Для работы с сервисом вычислений ArhiCloud через REST API возможно использовать любой лицензионный ключ, полученный в личном кабинете по адресу arhicloud.arhitex.com или предоставленный службой технической поддержки в рамках срока его действия.

Для получения Пробной лицензии и выпуска лицензионного ключа:

Создайте учётную запись в личном кабинете по адресу arhicloud.arhitex.com.
Создайте пробную лицензию. Во вкладке Лицензии нажмите «Создать лицензию» → Пробная → Активировать → Активировать.
Перейдите на вкладку «Лицензии». Кликните на иконку ключа в строке лицензии.
Во всплывающем окне кликните на кнопку «Сгенерировать ключ»
Полученный ключ может быть также использован для расчётов как через веб-версию, так и через Python API, а также напрямую через REST API.

Адрес API

Все эндпоинты для взаимодействия с солвером расположены по адресу api.arhitex.com.

Методы API

Для работы с вычислениями Пользователям доступны следующие основные методы.

Endpoint	Method	Description
/api/v1/calculations/	POST	Инициация расчёта
/api/v1/calculations/{id}/status	GET	Получение статуса расчёта
/api/v1/calculations/{id}/result	GET	Получение результата расчёта
/api/v1/calculations/{id}/log	GET	Получение лога расчёта

Этапы запуска вычислений

Запуск вычислений осуществляется в два шага:

Инициация расчёта – в учётной системе создается информация о расчёте и формируется уникальная ссылка для загрузки файла с моделью на сервер вычислений.
Загрузка файла модели для последующего расчёта.

После окончания процесса загрузки файла модели расчёт начнётся автоматически в соответствии с очередью.

Инициация расчёта

Инициация расчёта осуществляется через POST-запрос на точку /api/v1/calculations/. Авторизация осуществляется через X-API-KEY, указываемый в заголовке запроса.

resp = retry_wrapper(
        requests.post,
        check_status_code,
        f"https://{CALC_DOMAIN}/api/v1/calculations",
        headers={"X-API-KEY": X_API_KEY},
        json=calc_params,
    )

В данном примере calc_params – входные параметры солвера для расчёта модели.

calc_params = {"time_limit": 60, "gap": 0.001, "presolve": "on"}

В качестве ответа возвращается перечень данных, используемых далее для идентификации расчёта и загрузки файла на сервер вычислений.

{
    "calc_uid": "20240809_133839_bbc81c",
    "upload_data": {
        "fields": {
            "key": "20240809/13/3839_bbc81c/${filename}",
            "policy": "e0In0sIHsieC1hbXotZGF0ZSI6ICIyMDI0MDgwOVQxMDM4MzlaIn1dfQ==",
            "x-amz-algorithm": "AWS4-HMAC-SHA256",
            "x-amz-credential": "YCAJEIJpQM1BeYrWokqvuFAkb/20240809/ru-central1/s3/aws4_request",
            "x-amz-date": "20240809T103839Z",
            "x-amz-signature": "4499d530cc0c5598e62725d029cb7b6fc8cba030f4caf4a5e9a8d9e4604e1230"
        },
        "url": "https://api.arhitex.com/calcdata"
    }
}

Поле calc_uid используется для идентификации расчёта и дальнейших запросов дополнительной информации о расчёте. Информацию данного поля рекомендуем хранить на случай дальнейшего взаимодействия с расчётом или необходимости доступа к информации по расчёту по его завершении.

Загрузка модели

Загрузка модели осуществляется с использованием POST-запроса по адресу, предоставленному в ответе сервиса при инициализации расчёта в поле upload_data["url"] (в следующем примере адрес для загрузки сохранён в переменную url).

resp = retry_wrapper(requests.post,
        check_status_code,
        url, 
        data={
            "key":fields["key"],
            "X-Amz-Credential":fields['x-amz-credential'],
            "X-Amz-Algorithm":"AWS4-HMAC-SHA256",
            "X-Amz-Date":fields['x-amz-date'],
            "policy":fields['policy'],
            "X-Amz-Signature":fields['x-amz-signature'],
        },
        files = {
            'file': open(model_path, 'rb')
        }
    )

В поле data возвращаются уникальные значения, полученные в ответе при инициации расчёта на предыдущем этапе.

После завершения загрузки файла расчёт начинается автоматически, а при наличии очереди расчёт помещается в конец очереди и ожидает своего выполнения.

Загрузка модели с начальным решением

При необходимости запуска расчёта с учётом начального решения в задачах типа MILP следует процедуру, описанную в п.3.3. выполнить дважды.

Первым загружается файл с решением. Наименование файла с решением – start.sol. В случае, если загружаемый файл называется по-иному – решение не будет учтено при запуске расчёта. После загрузки файла с решением расчёт не начнётся автоматически, так как старт расчёта осуществляется только после загрузки файлов lp или mps.
'file': open('<path_to_start_sol_file>', 'rb')
После загрузки файла с решением загружается файл с моделью согласно описанной в п.3.3 последовательности шагов.

Проверка статуса вычислений

В ходе расчёта сервис возвращает статус расчёта. При осуществлении GET-запроса по адресу /api/v1/calculations/{id}/status, где id – идентификатор расчёта, Пользователь получает одну из пар возможных значений (status, minor). Например: {"status": "error", "minor": "TIME_AMOUNT_IS_OVER"}, что означает, что расчёт завершился с ошибкой и времени вычислений на аккаунте Пользователя недостаточно для запуска расчёта.

Авторизация осуществляется через X-API-KEY, указываемый в заголовке запроса.

def get_status(calc_uid):
    import json
    status = retry_wrapper(requests.get,
        check_status_code,
        f"https://{CALC_DOMAIN}/api/v1/calculations/{calc_uid}/status",
        allow_redirects=True,
        headers={"X-API-KEY": X_API_KEY},
    ).text
    try:
        status = json.loads(status)["status"]
    except:
        pass
    return status

Статусы решений

Status	Description
queued	Расчёт в очереди
calculating	Расчёт в процессе вычислений
done	Расчёт завершён
error	Ошибка

Minor	Description
TIME_AMOUNT_IS_OVER	Нарушение ограничений лицензии – у Пользователя закончился пакет минут
TIME_PER_CALC_VIOLATED	Нарушение требований к параметру time_limit – ограничение лицензии
SOLVER_POD_FAILED	Ошибка сервера вычислений
CALCULATION_FAILED	Ошибка солвера

Получение лога

Получение лога решение осуществляется путём отправки GET-запроса по адресу /api/v1/calculations/{id}/log, где id – идентификатор расчёта.

Авторизация осуществляется через X-API-KEY, указываемый в заголовке запроса.

def get_log(calc_uid):
    resp = retry_wrapper(requests.get,
        check_status_code,
        f"https://{CALC_DOMAIN}/api/v1/calculations/{calc_uid}/log",
        allow_redirects=True,
        headers={"X-API-KEY": X_API_KEY},
    )
    if resp.status_code == 200:
        with open("calc.log", 'wb') as f:
            f.write(resp.content)
        return resp.content
    else:
        print(resp.status_code)
    return ""

В данном примере осуществляется запрос на сервер вычислений, получение файла с решением и его запись в файл Пользователя.

Получение файла с решением

По результатам расчёта формируется файл с решением. Получить решение возможно путём отправки GET-запроса по адресу /api/v1/calculations/{id}/log, где id – идентификатор расчёта.

Авторизация осуществляется через X-API-KEY, указываемый в заголовке запроса.

def get_result(calc_uid):
    resp = retry_wrapper(requests.get,
        check_status_code,
        f"https://{CALC_DOMAIN}/api/v1/calculations/{calc_uid}/result",
        allow_redirects=True,
        headers={"X-API-KEY": X_API_KEY},
    )
    if resp.status_code == 200:
        with open("solution.sol", 'wb') as f:
            f.write(resp.content)
        return resp.content
    return ""

В данном примере осуществляется запрос на сервер вычислений, получение файла с решением и его запись в файл Пользователя.