Материал подготовлен командой Simple-Server для администраторов VPS и выделенных серверов. Команды и пути проверяйте на тестовой машине перед production.
Кратко о задаче
Использование API актуально в двух основных случаях:
- Отправка данных (POST, PUT, PATCH, DELETE). Информация отправляется в инфраструктуру для совершения каких-либо действий. Например, серверу или группе серверов отправляется команда на перезагрузку или обновление конфигурации. В первом случае отправляется просто команда, во втором случае команда дополняется обновленным конфигурационным файлом.
Отправка данных (POST, PUT, PATCH, DELETE). Информация отправляется в инфраструктуру для совершения каких-либо действий. Например, серверу или группе серверов отправляется команда на перезагрузку или обновление конфигурации. В первом случае отправляется просто команда, во втором случае команда дополняется обновленным конфигурационным файлом.
- Получение данных (GET). Информация получается из инфраструктуры для формирования каких-либо сведений. Например, на сервер отправляется запрос для получения актуальных данных о его работе, на основе которых формируется статистика в виде специальных метрик для системы мониторинга и аналитики. Это могут быть платежные транзакции, местонахождение серверов, потребление трафика или электроэнергии.
Получение данных (GET). Информация получается из инфраструктуры для формирования каких-либо сведений. Например, на сервер отправляется запрос для получения актуальных данных о его работе, на основе которых формируется статистика в виде специальных метрик для системы мониторинга и аналитики. Это могут быть платежные транзакции, местонахождение серверов, потребление трафика или электроэнергии.
Можно сказать, что API существует в рамках этих двух базовых понятий — отправка и получение данных, которые приводят к определенным результатам.
Таким образом, когда серверная инфраструктура масштабируется, становясь сложнее, ручное управление и сбор данных становятся трудоемкой или невозможной задачей.
В этот момент на сцену выходит API, с которым работают средства автоматизации — программы, которые выполняющие массовые задачи самостоятельно на основе тех указаний, которые им дал человек.
Поэтому, если издержки на выполнение операций начинают перевешивать их результативность, то пора задуматься об использовании API.
Управление серверами Simple-Server в curl
Публичный API, который предоставляет Simple-Server, позволяет управлять облачными ресурсами с помощью обыкновенных HTTP-запросов через методы GET, POST, PUT, PATCH, DELETE.
Большинство функций облака, доступных в панели управления Simple-Server, также доступны и в API. Таким образом можно автоматизировать уже привычные ручные сценарии управления облачной инфраструктурой Simple-Server.**
**
Создание токена авторизации
В любом запросе к API Simple-Server должен указываться специальный токен авторизации. Создать этот токен можно в панели управления в разделе API и Terraform.
Перейдя на страницу с токенами API, нужно нажать на кнопку Создать , после чего откроется страница конфигурации нового токена с рядом параметров:
- Имя токена. Произвольное имя исключительно для того, чтобы различать множество разных токенов внутри панели управления.
Имя токена. Произвольное имя исключительно для того, чтобы различать множество разных токенов внутри панели управления.
- Срок действия. Промежуток времени, в течении которого можно будет использовать токен. По истечении указанного срока токен удалится и доступ по нему прекратится.
Срок действия. Промежуток времени, в течении которого можно будет использовать токен. По истечении указанного срока токен удалится и доступ по нему прекратится.
- Настройки токена. Список разрешенных действий (права доступа), которые можно совершать через API с использованием этого токена.
Настройки токена. Список разрешенных действий (права доступа), которые можно совершать через API с использованием этого токена.
После указания всех параметров нужно нажать на кнопку Выпустить.
После этого появится окно со сгенерированным токеном. Его нужно скопировать и сохранить в защищенный текстовый файл.
Под каждую программу, использующую API, можно выделить отдельный токен только с тем набором прав, который необходим для корректной работы конкретно этой программы.
Таким образом, токен снимает необходимость в явной передаче логина и пароля при совершении запросов, а также позволяет устанавливать ограничения на доступ к определенным функциям в целях безопасности.
Чтобы быстро и легко использовать полученный токен во время выполнения запросов, его необходимо сохранить в виде переменной в терминале консоли:
TIMEWEB_CLOUD_TOKEN=eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6IjFrYnhacFJNQGJSI0tSbE1xS1lqIn0.eyJ1c2VyIjoieW41NTY2NSIsInR5cGUiOiJhcGlfa2V5IiwicG9ydGFsX3Rva2VuIjoiR1Z4Y0JBaGdnYXFXU1VZSEpDRnZneHQrZkFkSTdkN2ZOMXlhbnhVNzdneGNCOUQ3cGRjZ29vTC9FRzJRNnBEY0lMOXJJZms2K1ZiVjdvUDZSTHIxSENDa2pQZmIxTG5DRGwxSXQ5dGc2N2MvYlhQcUtHbVNnSSs4N1R5djBwRFNWZlBpWm13Q2U0b3dlT1Q5em9uZ1E0MkhTT2I2RDdBeWhUbktaU0JaRkd3PSIsImFwaV9rZXlfaWQiOiJmMjFjYzQ1NS0xZTUwLTRiNjAtYjVmMC05ZmExYzg3ZjM0MzYiLCJpYXQiOjE3MzEyNzkyMDF9.S5p_hmqgukvvPAfity7GPDEMmspV4KKZXT61XanduyD_SFx1iMsThgyY3kLCn4sSHQLh8VqBPu4rTUC5BsaIyaxR-4vFynWebqvEbirKttHtqH1IESysoNdPZfV2HY4906uefsqyOVChoQl8bCMiQ9HqFrYgPG-NnTzKBF0VemBAGZ8_np93frxiLwLaI7QwBrN9w5RMkcCWYDiPi3UEMrEhq10AaHfAWdMLdQzZ3UHn1yoSYxFlZ5_KMRsn7h5hC2DXzNNJ-EWGN943M4vGBKhBDRK2yBFXKVx3uA57P_hwmzjexxwcx0SrOz__wFKUHxc8WcGrjAATAQ5metYAv8ZcpRTAvGjrcIhDptuKlG4Pw_R_I3ZOF23j7B4ynfx36_RIC00fFMcXH4t6mZ0xF0Dndhbd77Vd701Mv4JRrCAb10WMAYh6T8O0_muvdcXKhXefbDHXeKu0wR4mq1FxJ8w2_-WFl47MNOxuew3tQLStWQwxSopbM9m5eJWwr5V2Для проверки работы токена можно запросить состояние баланса в аккаунте Simple-Server:
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN" \
"https://simple-server.tech/"Обратите внимание, что в команду запроса вставляется ранее созданная переменная TIMEWEB_CLOUD_TOKEN.
- Символ
\необходим, чтобы ввести команду в терминал консоли построчно. - Флаг
-Xуказывает метод запроса. - Флаг
-Hуказывает необходимый HTTP-заголовок.
Если запрос был отправлен корректно, в консольном терминале появится вывод с ответом сервера в формате JSON:
{"finances":{"balance":8.24,"currency":"RUB","discount_end_date_at":null,"discount_percent":0,"hourly_cost":0.41,"hourly_fee":0.41,"monthly_cost":300,"monthly_fee":300,"total_paid":930,"hours_left":20,"autopay_card_info":null,"total_balance":8.24454143},"response_id":"209c3c7a-c2da-45f1-9399-ad1874cfe1d6"}В более читабельном виде ответ сервера выглядит так:
{
"finances":
{
"balance":8.24,
"currency":"RUB",
"discount_end_date_at":null,
"discount_percent":0,
"hourly_cost":0.41,
"hourly_fee":0.41,
"monthly_cost":300,
"monthly_fee":300,
"total_paid":930,
"hours_left":20,
"autopay_card_info":null,
"total_balance":8.24454143
},
"response_id":"209c3c7a-c2da-45f1-9399-ad1874cfe1d6"
}Еще одна простая команда — перезагрузка удаленного сервера.
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN" \
"https://simple-server.tech/"В этой команде {server_id} нужно заменить на уникальный идентификатор облачного сервера. Взять этот идентификатор можно из адресной строки браузера.
Таким образом, команда перезагрузки облачного сервера будет выглядеть примерно так:
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN" \
"https://simple-server.tech/"Обратите внимание, что в этом случае используется метод POST, а не GET. Таким образом, этот запрос изменяет состояние сервера, а не просто получает данные.**
**
Управление серверами Simple-Server в Golang
Разумеется, API необходим не для выполнения запросов через терминал консоли, а для управления облачными серверами из кода программ.
Поэтому разберём несколько простых примеров работы с API в языке программирования Golang.
В этом руководстве используется интерпретатор Go версии 1.23.3, запущенный в операционной системе Ubuntu 22.04 на облачном сервере Simple-Server.**
**
Если в вашей системе еще не установлен Golang, то его необходимо загрузить с официального сайта в формате архива:
wget https://go.dev/dl/go1.23.3.linux-amd64.tar.gz -O go.tar.gz
sudo tar -xzvf go.tar.gz -C /usr/localДалее нужно указать бинарный файл в переменной PATH:
echo export PATH=$HOME/go/bin:/usr/local/go/bin:$PATH >> ~/.profileДля начала создадим отдельную директорию для скриптов на Go:
Теперь можно инициализировать проект Go:
Получение информации о балансе
Как и в случае с curl, наиболее простая вещь, которую можно сделать. — проверить состояние баланса на аккаунте.
Создадим отдельный скрипт для этого:
Скрипт будет представлять собой вот такой код:
Однако, чтобы скрипт работал корректно, нужно перед его запуском в терминале консоли определить экспортируемую переменную с токеном авторизации:
export TIMEWEB_CLOUD_TOKEN="тут_токен"И только после этого можно запустить скрипт:
Результатом работы этого скрипта станет следующий консольный вывод:
{"finances":{"balance":48.82,"currency":"RUB","discount_end_date_at":null,"discount_percent":0,"hourly_cost":0.41,"hourly_fee":0.41,"monthly_cost":300,"monthly_fee":300,"total_paid":980,"hours_left":119,"autopay_card_info":null,"total_balance":48.81831205},"response_id":"7f849b90-5d42-44c7-a90a-a12875878bb3"}Как видно, ответ сервера такой же, как и в случае с cURL.**
**
Перезагрузка сервера в Go
Точно также можно перезагрузить сервер из кода программы на Go.
Создадим еще один скрипт:
Содержимым которого выступит код, практически аналогичный предыдущему примеру:
Аналогично перед запуском скрипта нужно убедиться в существовании экспортируемой переменной TIMEWEB_CLOUD_TOKEN, содержащей токен авторизации.
Либо можно использовать токен приложения внутри кода вашей программы в виде строковой переменной.
Управление серверами Simple-Server в Python
Функционал, аналогичный терминалу curl и скриптам Go, можно реализовать на языке программирования Python.
Для простоты файлы с кодом на Python будем размещать в том же каталоге с проектом Go.**
**
Получение данных о балансе
Создадим файл со скриптом, который будет запрашивать платежную информацию аккаунта Simple-Server:
import os
import requests
# объявляем список заголовков
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + os.getenv('TIMEWEB_CLOUD_TOKEN', ''),
}
# выполняем запрос к серверу
response = requests.get('https://simple-server.tech/', headers=headers)
print(response.content) # выводим ответ сервера в консольПосле чего в консольном терминале должен появиться ответ удаленного сервера:
b'{"finances":{"balance":49.64,"currency":"RUB","discount_end_date_at":null,"discount_percent":0,"hourly_cost":0.41,"hourly_fee":0.41,"monthly_cost":300,"monthly_fee":300,"total_paid":980,"hours_left":121,"autopay_card_info":null,"total_balance":49.63798417},"response_id":"e5c379ad-d7e6-4963-9774-b457e52b9148"}'Перезагрузка сервера в Python
Теперь создадим отдельный скрипт, выполняющий перезагрузку сервера:
import os
import requests
# объявляем список заголовков
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + os.getenv('TIMEWEB_CLOUD_TOKEN', ''),
}
response = requests.post('https://simple-server.tech/', headers=headers) # в адресе запроса на месте цифр указываем уникальный идентификатор облачного сервера
print(response) # выводим СТАТУС ответ сервера в консольТеперь запускаем выполнение скрипта:
В консольном терминале появится вывод, содержащий статус выполненного действия:
После этого облачный сервер начнет перезагружаться.
Перезагрузка всех существующих серверов
Как правило с помощью API управляют не одним сервером, а несколькими. Поэтому рассмотрим наипростейший пример одновременной перезагрузки всех имеющихся облачных серверов.
Для этого создадим новый файл:
И поместим в него следующий код:
Соответственно, запустить скрипт можно следующим образом:
В этом примере сначала запрашивается список всех существующих серверов, после чего по нему выполняется итерация, внутри которой отправляются запросы на перезагрузку каждого сервера через уникальный идентификатор.
Более подробно о структуре ответа на запрос списка серверов можно узнать в документации API Simple-Server.**
**
Нужен сервер для практики? Арендуйте VPS/VDS в России — root-доступ, NVMe, DDoS-защита и поддержка 24/7.