Взаимодействие с TrinityCore с использованием SOAP (TBD)

2024-07-12

оригинал:SOAP с TrinityCore | TrinityCore MMo Project Wiki

Как взаимодействовать с TC с помощью SOAP

SOAP расшифровывается как Simple Object Access Protocol и является более старой формой стандартизированного протокола доступа к веб-службам, аналогичного REST. Если необходимая конфигурация имеется, вы можете использовать SOAP для отправки команд на сервер TrinityCore.
Хороший способ понять SOAP — сравнить его с современным REST. Следующая статья очень хорошо объясняет это – https://smartbear.com/blog/soap-vs-rest-whats-the-difference/.
Основное различие между ними заключается в том, что SOAP полностью полагается на XML для предоставления ответов и приема полезных данных. PHP предоставляет некоторые методы, упрощающие этот процесс, но в зависимости от вашего варианта использования вам может потребоваться знание XML.

Конфигурация

worldserver.conf
Убедитесь, что настройки в файле конфигурации установлены правильно.


#    SOAP.Enable
#        Description: Enable soap service.
#        Default:     0 - (Disabled)
#                     1 - (Enabled)
SOAP.Enabled = 1
 
#    SOAP.IP
#        Description: Bind SOAP service to IP/hostname.
#        Default:     "127.0.0.1" - (Bind to localhost)
SOAP.IP = "127.0.0.1"
 
#    SOAP.Port
#        Description: TCP port to reach the SOAP service.
#        Default:     7878
SOAP.Port = 7878

Учитывая вашу конкретную конфигурацию доступа RBAC, вам также потребуется учетная запись пользователя с разрешениями на использование команд GM. Возможно, было бы хорошей идеей создать учетную запись с ограниченным доступом специально для этой цели, а не ту, которая используется одним человеком.

ПРИМЕЧАНИЕ. На момент написания TC 335a поддерживает только HTTP, поэтому будьте осторожны и не отправляйте секреты (пароли и т. д.) таким способом. Предполагается, что все передаваемое передается в виде открытого текста и может быть прочитано кем угодно.
Если вы планируете подключаться удаленно через SOAP, вам обязательно следует принять меры для обеспечения безопасного соединения. Один из возможных подходов — использование обратного прокси-сервера SSL через Apache или Nginx. Однако это выходит за рамки настоящего руководства и не будет включено.

HTTP-клиент для прототипирования

Есть клиенты для быстрого установления соединения и проверки консольных команд:
почтальон: https://www.postman.com/ (сеть, настольный агент/клиент)
бессонница：https://insomnia.rest/
Соловей-соловей: https://nightingale.rest/
Все они предлагают множество деталей, но в конечном итоге работают примерно одинаково. Спасибо Jackpoz за конкретные действия для Postman — https://www.postman.com/.
Postman поставляется в двух вариантах: веб-интерфейс (а также прокси-сервер, который можно установить для выполнения запросов локального хоста) и полноценное клиентское настольное приложение. Инструкция в обоих случаях одинакова.
В разделе «Моя рабочая область» найдите кнопку «Импорт». Вы будете использовать исходный текстовый вариант.
Скопируйте и вставьте следующий JSON в текстовое поле. Обязательно обновите учетные данные в item.request.auth.basic для пользователя GM, упомянутого ранее.


{
  "info": {
    "name": "TC SOAP",
    "schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"
  },
  "item": [
    {
      "name": "server info",
      "request": {
        "auth": {
          "type": "basic",
          "basic": {
            "username": "CHANGEME",
            "password": "CHANGEME",
            "showPassword": false
          }
        },
        "method": "POST",
        "header": [],
        "body": {
          "mode": "raw",
          "raw": "<?xml version="1.0" encoding="utf-8"?>rn<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:TC">rn<SOAP-ENV:Body>rn<ns1:executeCommand>rn<command>server info</command>rn</ns1:executeCommand>rn</SOAP-ENV:Body>rn</SOAP-ENV:Envelope>",
          "options": {
            "raw": {
              "language": "xml"
            }
          }
        },
        "url": "http://127.0.0.1:7878"
      },
      "response": []
    }
  ]
}

Вы должны думать о TC SOAP как о коллекции для импорта. Нажмите «Импортировать».
В результате в новую коллекцию будет добавлен правильный метод HTTP (POST) и сведения на вкладках «Авторизация» и «Тело».
На вкладке «Тело» обратите внимание на команды полезной нагрузки XML и информации о сервере, которые предварительно заполнены.
Нажатие кнопки «Отправить» отправит запрос и предоставит ответ в формате XML.
В правой части интерфейса Postman есть</> Символ откроет фрагмент кода, который может преобразовать запрос на выбранный вами язык.
¶Использование PHP
Чтобы взаимодействовать с TrinityCore с помощью PHP, вам необходимо убедиться, что у вас установлено расширение PHP-soap. Также убедитесь, что вы используете версию PHP, которая все еще активно поддерживается. Примеры кода были протестированы на PHP7.4–PHP8.1.
Во всех этих примерах URI urn:TC является обязательным параметром, поскольку мы не предоставили документ WSDL.
SoapClient-https://www.php.net/manual/en/class.soapclient.php


$command  = 'server info';
 
$opts = [
    'http' => [
        'header' => "Authorization: Basic " . base64_encode("USERNAME:PASSWORD")
    ]];
 
$client = new SoapClient($wsdl = null, [
    'stream_context' => stream_context_create($opts),
    'location' => 'http://127.0.0.1:7878',
    'uri' => 'urn:TC',
]);
 
try {
    $result = $client->executeCommand(new SoapParam($command, 'command'));
} catch (Exception $e) {
    die($e->getMessage());
}
 
echo $result;

Обратите внимание, что мы передаем заголовок HTTP basic authorization с именем пользователя и паролем в кодировке base64 (разделенными двоеточием). В качестве альтернативы вы можете пропуститьstream_contextи вместо этого включите имя пользователя (для входа) и пароль в конфигурацию SoapClient.


$command  = 'server info';
 
$client = new SoapClient($wsdl = null, [
    'location' => 'http://127.0.0.1:7878',
    'uri' => 'urn:TC',
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
]);
 
try {
    $result = $client->executeCommand(new SoapParam($command, 'command'));
} catch (Exception $e) {
    die($e->getMessage());
}
 
echo $result;

Оба подхода хороши, но не обманывайтесь! Кодировка Base 64 сама по себе не делает ее более безопасной.

Помните, что клиент SOAP может распознавать только сбои подключения или неправильные настройки.Он не будет знать, если вы предоставили недействительную команду.. Так что вам решать, проанализировать результаты и решить, был ли ожидаемый результат успешным или нет. Вывод будет таким же, как если бы вы выполнили команду на консоли.

Наконец, если вы не хотите полагаться на расширение или клиент SOAP, вы можете сформировать полезную нагрузку XML и разобрать полученный ответ XML самостоятельно. Вам все равно понадобитсярасширение cURL, но обычно он доступен, если не включен по умолчанию.


<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:TC">
    <SOAP-ENV:Body>
        <ns1:executeCommand>
            <command>server info</command>
        </ns1:executeCommand>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


$curl = curl_init();
 
curl_setopt_array($curl, [
    CURLOPT_POSTFIELDS => $payload, // $payload is the XML provided above
    CURLOPT_URL => 'http://127.0.0.1:7878',
    CURLOPT_TIMEOUT => 0,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        "Authorization: Basic " . base64_encode("{$user}:{$pass}"),
        'Content-Type: application/xml',
    ],
]);
 
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Обмен технологиями