Interagindo com TrinityCore usando SOAP (TBD)

2024-07-12

original:SOAP com TrinityCore | TrinityCore MMo Project Wiki

Como interagir com TC usando SOAP

SOAP significa Simple Object Access Protocol e é uma forma mais antiga de protocolo de acesso a serviços da web baseado em padrões semelhante ao REST. Contanto que a configuração necessária esteja em vigor, você pode aproveitar o SOAP para enviar comandos ao servidor TrinityCore.
Uma boa maneira de entender o SOAP é compará-lo ao REST contemporâneo. O artigo a seguir explica isso muito bem – https://smartbear.com/blog/soap-vs-rest-whats-the-difference/.
A principal diferença entre os dois é que o SOAP depende inteiramente de XML para fornecer respostas e aceitar cargas úteis. O PHP fornece alguns métodos para facilitar esse processo, mas dependendo do seu caso de uso, pode ser necessário estar familiarizado com XML.

Configuração

servidormundial.conf
Certifique-se de que as configurações no arquivo de configuração estejam definidas corretamente.


#    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

Dada a sua configuração específica de acesso ao RBAC, você também precisará de uma conta de usuário com permissões para usar comandos GM. Pode ser uma boa ideia criar uma conta de acesso limitado especificamente para esse fim, em vez de uma conta usada por uma pessoa.

NOTA: No momento em que este artigo foi escrito, o TC 335a suporta apenas HTTP, portanto, tome cuidado para não enviar segredos (senhas, etc.) dessa forma. Presume-se que tudo o que é passado está em texto claro e pode ser lido por qualquer pessoa.
Se você planeja se conectar remotamente via SOAP, você definitivamente deve tomar medidas para garantir uma conexão segura. Uma abordagem potencial é através de um proxy SSL reverso através do Apache ou nginx. No entanto, isso está fora do escopo deste guia e não será incluído.

Cliente HTTP para prototipagem

Existem clientes para estabelecer rapidamente uma conexão e testar comandos do console:
carteiro: https://www.postman.com/ (rede, agente/cliente de desktop)
insônia：https://insomnia.rest/
Rouxinol rouxinol: https://nightingale.rest/
Todos eles oferecem uma variedade de detalhes, mas funcionam praticamente da mesma forma. Obrigado ao Jackpoz por fornecer as etapas específicas para o Postman - https://www.postman.com/.
O Postman vem em dois sabores: uma interface web (bem como um proxy que pode ser instalado para executar solicitações de host local) e um aplicativo de desktop cliente completo. As instruções são as mesmas em ambos os casos.
Em “Meu espaço de trabalho”, encontre o botão “Importar”. Você usará a opção de texto original.
Copie e cole o seguinte JSON na caixa de texto. Certifique-se de atualizar as credenciais em item.request.auth.basic para o usuário GM mencionado anteriormente.


{
  "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": []
    }
  ]
}

Você deve pensar no TC SOAP como uma coleção para importar. Clique em Importar.
Isso preencherá a nova coleção com o método HTTP correto (POST) e os detalhes nas guias Autorização e Corpo.
Na guia Corpo, observe a carga útil XML e os comandos de informações do servidor que são pré-preenchidos para você.
Clicar no botão "Enviar" enviará a solicitação e fornecerá uma resposta XML.
No lado direito da interface do Postman, um</> símbolo abrirá um trecho de código que pode converter a solicitação no idioma de sua escolha.
¶Usando PHP
Para interagir com TrinityCore usando PHP, você precisa ter a extensão PHP-soap instalada. Certifique-se também de estar usando uma versão do PHP que ainda tenha suporte ativo. Exemplos de código foram testados em PHP7.4 a PHP8.1.
Em todos esses exemplos, o URI urn:TC é um parâmetro obrigatório porque não fornecemos um documento 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;

Observe que estamos passando um cabeçalho de autorização básica HTTP com nome de usuário e senha codificados em base64 (separados por dois pontos). Como alternativa, você pode omitir ostream_contextparâmetro e, em vez disso, inclua um nome de usuário (login) e uma senha na configuração do 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;

Qualquer abordagem é boa - mas não se deixe enganar! A codificação Base 64 não a torna inerentemente mais segura.

Lembre-se de que o cliente SOAP só pode reconhecer falhas de conexão ou configurações incorretas.Ele não saberá se você forneceu um comando inválido. Então, cabe a você analisar os resultados e decidir se o resultado pretendido foi um sucesso ou não. A saída será exatamente como se você tivesse executado o comando no console.

Por fim, se você preferir não depender da extensão SOAP ou do cliente, você pode formar o payload XML e analisar a resposta XML resultante você mesmo. Você ainda precisará doextensão cURL, mas isso geralmente está disponível se não estiver habilitado por padrão.


<?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;

Compartilhamento de tecnologia