REST API подключение к серверу Kaseya на примере PHP программы

Введение

Для взаимодействия программ создан интерфейс взаимодействия через протокол REST API. Протокол взаимодействия описан на английском языке по ссылке:

http://help.kaseya.com/webhelp/EN/restapi/9040000/#home.htm

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

https://#SERVERNAME#/api/v1.0/swagger, где #SERVERNAME# это имя или адрес сервера Kaseya.

Примеры описанные здесь будут создаваться для языка PHP. Примеры для языка C# приведены на странице руководства по ссылке выше.

Подключение к REST API

Для выполнения подключения необходимо зарегистрировать пользователя на сервере в разделе сервера Kaseya “System > User Security > Users”. В подключении к серверу через REST API участвует учетная запись пользователя ($username) и пароль ($password). Также нам понадобится URL сервера ($url) вида https://#SERVERNAME#/api/v1.0/auth, где #SERVERNAME# это имя или адрес сервера Kaseya. Для генерации нам понадобится целое 32-битное случайное число ($Random). Я воспользовался функцией rand() для генерации, но рекомендуется использовать random_int() для получения более случайного результата, пригодного для использования в шифровании, поэтому для создания серьезных проектов рекомендую пользоваться ей и для этого использовать PHP версии старше 7.1.0. Мы же используем случайное число как пример генерации подключения к серверу. У нас есть исходные данные и мы приступим к сборке строки подключения.

  1. В первую очередь сгенерируем случайное 32-битное целое число:
    $Random = rand(0,2147483646);
  2. Теперь нужно получить хэш SHA-256 от пароля и записать его в переменную $RawSHA256Hash:
    $RawSHA256Hash = hash(‘sha256’, $password);
  3. Собираем в длинную строку пароль и учетную запись пользователя и от полученного результата получаем хэш SHA-256 и записываем его в переменную $CoveredSHA256HashTemp:
    $CoveredSHA256HashTemp = hash(‘sha256’,$password.$username);
  4. Полученный в предыдущем вычислении результат соберем в общую строку со случайным числом и от результата вычисляем хэш SHA-256 и записываем его в переменную $CoveredSHA256Hash:
    $CoveredSHA256Hash = hash(‘sha256’,$CoveredSHA256HashTemp.$Random);
  5. Ту же последовательность проделываем еще раз, но вычисляем хэш SHA-1. Получаем хэш SHA-1 от пароля и записать его в переменную $RawSHA1Hash:
    $RawSHA1Hash = sha1($password);
  6. Собираем в длинную строку пароль и учетную запись пользователя и от полученного результата получаем хэш SHA-1 и записываем его в переменную $CoveredSHA1HashTemp:
    $CoveredSHA1HashTemp = sha1($password.$username);
  7. Полученный в предыдущем вычислении результат соберем в общую строку со случайным числом и от результата вычисляем хэш SHA-1 и записываем его в переменную $CoveredSHA1Hash:
    $CoveredSHA1Hash = sha1($CoveredSHA1HashTemp.$Random);
  8. Полученные результаты собираем в строку подключения $string:
    $string = “user=$username,pass2=$CoveredSHA256Hash,pass1=$CoveredSHA1Hash,rpass2=$RawSHA256Hash,rpass1=$RawSHA1Hash,rand2=$Random”;
  9. Полученную строку кодируем Base64 и записываем в переменную $header:
    $header = base64_encode($string);
  10. Собираем заголовки для запроса GET в переменную $headers:
    $headers = array( ‘Content-Type:application/json’, ‘Authorization: Basic ‘. $header);
  11. Теперь будем подготавливать запрос GET к серверу Kaseya. Выполнять будем с использованием библиотеки libcurl. Первым делом создадим соединение и запишем его в переменную $ch:
    $ch = curl_init();
  12. Далее установим следующие параметры для сеанса CURL: установим, чтобы нам вернулся необработанный ответ:   
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  13. Установим HTTP метод авторизации Basic:
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);  
  14. Передадим URL авторизации на нашем сервере Kaseya:
    curl_setopt($ch, CURLOPT_URL, $url);
  15. Передаем собранные нами заголовки:
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  16. Выполняем вызов и результаты запишем в переменную $result:
    $result = curl_exec($ch);
  17. По окончании закрываем сессию CURL:
    curl_close($ch);
  18. Теперь мы получили ответ от сервера и если мы правильно все собрали, то получим JSON строку в которой нас интересуют поле Error – выполнен ли запрос правильно и успешно и поле Token, которое в случае успешного выполнения содержит значение сессии, которое мы будем использовать для других подключений:
    { “Result”: { “TenantId”: “1”, “Token”: “64996057”, “UserName”: “nautical”, “RoleId”: 2, “ScopeId”: “2”, “AdminId”: 97217399, “MachineId”: null, “MachineGroupName”: null, “CultureInfo”: “en-US”, “TimePref”: “Browser”, “OffSetInMinutes”: 0, “Attributes”: null }, “ResponseCode”: 0, “Status”: “OK”, “Error”: “None” }
  19. Разберем строку при помощи json_decode():
    $obj=json_decode($result);
    В результате получим:
    stdClass Object ( [Result] => stdClass Object ( [TenantId] => 1 [Token] => 96613958 [UserName] => nautical [RoleId] => 2 [ScopeId] => 2 [AdminId] => 97217399 [MachineId] => [MachineGroupName] => [CultureInfo] => en-US [TimePref] => Browser [OffSetInMinutes] => 0 [Attributes] => ) [ResponseCode] => 0 [Status] => OK [Error] => None )
    Нужные нам объекты доступны в переменных $obj->{‘Error’} и $obj->{‘Result’}->{‘Token’}

 

Получаем список агентов в PHP запросе

Для этого воспользуемся функцией получения списка агентов, доступной по адресу https://#SERVERNAME#/api/v1.0/assetmgmt/agents, где #SERVERNAME# это имя или адрес сервера Kaseya. Для подготовки запроса сначала выполним подключение к серверу, как было описано ранее и в ответе подключения получим Token сессии. Нужно помнить. что данный Token действует только 5 минут, по истечении которых нужно выполнить повторный запрос на подключение. Получив Token сформируем