RU/Resource Web Access

From Multi Theft Auto: Wiki

Сервер Multi Theft Auto предоставляет веб-интерфейс, который может различными способами использоваться ресурсами. Цель данной статьи - объяснить, что это за способы и как их можно использовать.

Обзор

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

Страницы

Указание файла в meta

В meta-файле вашего ресурса вы можете указать доступность определенных файлов через веб-браузер. Чтобы это сделать, добавьте строку:

<html src="имяфайла.расширение" />

Затем вы сможете получить доступ к этому файлу через веб-браузер по адресу: http://адрес:порт/имяресурса/имяфайла.расширение
Например, на локальном сервере, использующем http-порт по умолчанию с запущенным webmap это: http://127.0.0.1:22005/webmap/map.htm


Бинарные файлы

Несмотря на обманчивое название, файлы, указанные с использованием узла html, могут быть любого типа. Если они являются бинарными (двоичными) файлами (типа картинок, zip-архивов), вам понадобится указать это в meta-файле, добавив raw="true" к узлу (строке с) html. Это значит, что файлы не будут предварительно обрабатываться перед отправкой веб-браузеру.

Например:

<html src="image.gif" raw="true" />

Анализируемые файлы

Если файл не имеет в meta-файле пометки "raw", тогда перед тем, как быть возвращенным клиенту, он проходит через процессор предварительной обработки. Этот препроцессор в целом работает как в PHP или ASP, но использует LUA. Вы можете встраивать стандартные MTA-скрипты вовнутрь HTML-страниц, имея контроль над выводом. Работают почти все стандартные функции MTA, плюс к ним добавляются еще некоторые специальные HTTP функции, такие как httpWrite - функция, выводящая текст в буфер.

Например:

<html>
    <body>
        Этот ресурс называется <* httpWrite( getResourceName(getThisResource()) ) *>
    </body>
<html>

Имеется краткая альтернатива (совместно с PHP и ASP) этого кода, а это значит, что код выше можно также записать как:

<html>
    <body>
        Этот ресурс называется <* = getResourceName(getThisResource()) *>
    </body>
<html>

Отдельно от HTTP функций, встроенный Lua имеет доступ к следующим переменным среды, содержащим информацию про то, как была запрошена страница:

  • table requestHeaders: Эта таблица содержит все заголовки, которые были запрошены со страницей. Вы можете установить возвращаемые заголовки через использование httpSetResponseHeader.
  • table form: Эта таблица содержит все данные формы, переданные странице с использованием HTTP POST совмщенно с любыми переменными, переданными в строке запроса с HTTP GET.
  • table cookies: Это таблица со всеми cookies. Вы можете редактировать cookies с использованием httpSetResponseCookie.
  • string hostname: Это строка, содержащая IP адрес или имя хоста, запросившего страницу.
  • string url: Это URL страницы.
  • account user: Это аккаунт текущего пользователя.

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

Вызовы

Вы можете указать, чтобы определенные экспортированные функции вашего ресурса могли быть вызваны через HTTP-интерфейс. Все SDK (указанные ниже) позволяют вам вызывать эти функции удаленно.

Для указания экспортированной функции, доступной по http, добавьте в файл meta.xml следующее:

<export function='functionName' http='true' />

Вы можете писать свою функцию как и любую другую обычную, возвращать сколько вам угодно много значений, включия таблицы, ресурсы и, что более важно, элементы. Тем не менее вы не можете возвращать другие значения 'userdata' типа xmlnodes или функций.

Протокол

[[{{{image}}}|link=]] Note: Вам не нужно этого знать за исключением случаев, если вы пишете свой собственный код HTTP-запроса. Можно просто воспользоваться одним из SDK, указанных ниже.

Вызовы выполняются через запрос http://<ваш IP>:<ваш порт>/<имя_ресурса>/call/<имя_экспортированной_функции> с использованием HTTP POST. Тело запроса должно быть JSON массивом из аргументов для функции.

Запрос возвратит JSON-массив значений, возвращенных функцией как HTTP-ответ.

Сервер поддерживает HTTP Basic идентификацию, вы можете конфигурировать доступ через ACL и встроенную систему аккаунтов.

Вызовы из HTTP веб-интерфейса

Вызовы, вероятно, наиболее легки из веб-интерфейса и могут выполняться практически без усилий.

Во-первых, добавьте в файл meta.xml следующее:

<include resource="ajax" />

Во-вторых, в секцию <head> страницы, из который вы хотите производить вызов, добавьте следующее:

<* = exports.ajax:start(getResourceName(getThisResource())) *>

Наконец, вы можете создать на своей странице javascript-блок и вызывать свои функции практически так же, как если бы они были локальными. Единственное различие в том, что вызовы асинхронны - вам следует указывать callback-функцию последним аргументом для своего вызова. Она будет использоваться для возврата каких-либо значений основной функцией.

Вот простой пример.

meta.xml

<meta>
   <include resource="ajax" />
   <script src='code.lua' />
   <html src='page.htm' default='true' />
   <export function='showChatMessage' http='true' />
</meta>

code.lua

function showChatMessage ( message )
    outputChatBox ( message )
    return 5;
end

page.htm

<html>
    <head>
        <* = exports.ajax:start(getResourceName(getThisResource())) *>
        <script type='text/javascript'>
            function say() {
                var message = document.getElementById('message')
                showChatMessage ( message.value, 
                    function ( number ) {
                        // функция была вызвана и что-то вернула
                        message.value = "Функция вернула " + number;
                    }
                );
            }
        </script>
    </head>
    <body>
        <input type='text' id='message' /><input type='button' value='say' onclick='say();' />
    </body>
</html>

Вы можете видеть (довольно сложные) образцы того, как это можно сделать, в ресурсах resourcebrowser, resourcemanager и webadmin.

Обезопашивание веб-интерфейса

ACL предоставляет некоторое количество прав, которые могут влиять на то, какие файлы смогут быть доступны.

  • general.http: Если выключен, никакие из http файлов не будут доступны (за исключением игровых клиентов)
  • resource.ResourceName: Если выключен, никакие из файлов ресурса не будут доступны
  • resource.ResourceName.file.FileName: Если выключен, файл с данным названием не будет доступен
  • resource.ResourceName.function.FunctionName: Если выключен, функцию невозможно будет вызвать

Они работают как и другие ACL права - вы можете их отключить для обычных пользователей и просто включить для группы Admin, или любой другой, которой вы пожелаете.

SDK

Доступно некоторое количество так называемых 'SDK', которые позволяют вам сообщаться с сервером через другие языки программирования. С их помощью вы (теоретически) можете писать целые игровые режимы. На практике, возможно, не очень хорошая идея, но это тем не менее является очень полезным для статистики и администрирования. PHP SDK - наиболее развитая версия. Не стесняйтесь модифицировать или создавать собственные SDK - если решитесь, пожалуйста, пришлите нам копию.

Также смотрите

callRemote - Позволяет игровым серверам вызывать функции на PHP-страницах (с PHP SDK) и других игровых серверах.