SOAP を使用した TrinityCore との対話 (TBD)

2024-07-12

オリジナル：TrinityCore を使用した SOAP | TrinityCore MMo プロジェクト Wiki

SOAP を使用して TC と対話する方法

SOAP は Simple Object Access Protocol の略で、REST に似た標準ベースの Web サービスアクセスプロトコルの古い形式です。必要な構成が整っている限り、SOAP を利用してコマンドを TrinityCore サーバーに送信できます。
SOAP を理解する良い方法は、SOAP を最新の REST と比較することです。これについては、次の記事で詳しく説明しています – https://smartbear.com/blog/soap-vs-rest-whats-the-difference/。
2 つの主な違いは、SOAP が応答の提供とペイロードの受け入れを XML に完全に依存していることです。 PHP には、このプロセスを容易にするためのメソッドがいくつか用意されていますが、ユースケースによっては、XML に精通している必要がある場合があります。

構成

ワールドサーバー.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 コマンドを使用する権限を持つユーザーアカウントも必要になります。 1 人が使用するアカウントではなく、この目的専用にアクセス制限付きのアカウントを作成することをお勧めします。

注: この記事の執筆時点では、TC 335a は HTTP のみをサポートしているため、この方法でシークレット (パスワードなど) を送信しないように注意してください。渡されるものはすべて平文であり、誰でも読むことができると想定されています。
SOAP 経由でリモート接続する予定がある場合は、確実に安全な接続を確保するための措置を講じる必要があります。考えられるアプローチの 1 つは、Apache または nginx を介したリバース SSL プロキシを使用することです。ただし、これはこのガイドの範囲外であるため、含まれません。

プロトタイピング用のHTTPクライアント

接続を迅速に確立し、コンソールコマンドをテストするためのクライアントがあります。
ポストマン: https://www.postman.com/ (ネットワーク、デスクトップエージェント/クライアント)
不眠症：https://insomnia.rest/
ナイチンゲールナイチンゲール：https://nightingale.rest/
これらはすべてさまざまな詳細を提供しますが、最終的にはほぼ同じように機能します。 Postman の具体的な手順を提供してくれた Jackpoz (https://www.postman.com/) に感謝します。
Postman には、Web インターフェイス (およびローカルホスト要求を実行するためにインストールできるプロキシ) と完全なクライアントデスクトップアプリケーションの 2 つの種類があります。どちらの場合も手順は同じです。
[マイワークスペース] の下にある [インポート] ボタンを見つけます。オリジナルのテキストオプションを使用します。
次の 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の使用
PHP を使用して TrinityCore と対話するには、PHP-soap 拡張機能がインストールされていることを確認する必要があります。また、現在もアクティブにサポートされているバージョンの PHP を使用していることを確認してください。コード例は PHP7.4 から PHP8.1 でテストされました。
これらすべての例では、WSDL ドキュメントを提供していないため、urn:TC URI は必須パラメーターです。
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基本認証ヘッダーに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;

技術共有