RU/Resource Web Access: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
Line 1: Line 1:
{{translate}}
Сервер Multi Theft Auto предоставляет веб-интерфейс, который может различными способами использоваться ресурсами. Цель данной статьи - объяснить, что это за способы и как их можно использовать.
The Multi Theft Auto Server provides a web interface that resources can use in a variety of ways. This document's purpose is to explain what these ways are and how to go about using them.


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


==Pages==
==Страницы==
===Добавление файла в meta===
===Указание файла в meta===
Вы можете обозначить в meta файле своего ресурса, определенные данные доступные через веб-сервер. Чтобы сделать это, добавьте строку:
В meta-файле вашего ресурса вы можете указать доступность определенных файлов через веб-браузер. Чтобы это сделать, добавьте строку:
<syntaxhighlight lang="xml">
<syntaxhighlight lang="lua" lang="xml">
<html src="filename" />
<html src="имяфайла.расширение" />
</syntaxhighlight>
</syntaxhighlight>
Вы можете получить доступ к этому файлу через веб-браузер, перейдя по следующей ссылке:
Затем вы сможете получить доступ к этому файлу через веб-браузер по адресу: http://адрес:порт/имяресурса/имяфайла.расширение<br/>
http://host:port/resourcename/filename
Например, на локальном сервере, использующем http-порт по умолчанию с запущенным webmap это: http://127.0.0.1:22005/webmap/map.htm
 


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


Пример:
Например:
<syntaxhighlight lang="xml">
<syntaxhighlight lang="lua" lang="xml">
<html src="image.gif" raw="true" />
<html src="image.gif" raw="true" />
</syntaxhighlight>
</syntaxhighlight>


===Parsed files===
===Анализируемые файлы===
If a file is not specified in the meta file as "raw", then it is passed through a pre-processor before it is returned to the client. This pre-processor works much like PHP or ASP, but uses LUA. You can embed standard MTA scripts within HTML pages, controlling the output. Almost all standard MTA functions work, plus a number of special [[Template:HTTP functions|HTTP Functions]], such as [[httpWrite]], a function that outputs text to the buffer.
Если файл не имеет в meta-файле пометки "raw", тогда перед тем, как быть возвращенным клиенту, он проходит через процессор предварительной обработки. Этот препроцессор в целом работает как в PHP или ASP, но использует LUA. Вы можете встраивать стандартные MTA-скрипты вовнутрь HTML-страниц, имея контроль над выводом. Работают почти все стандартные функции MTA, плюс к ним добавляются еще некоторые специальные [[Template:HTTP functions|HTTP функции]], такие как [[httpWrite]] - функция, выводящая текст в буфер.


Пример:
Например:
<syntaxhighlight lang="lua">[html]
<syntaxhighlight lang="lua" lang="html">
<html>
<html>
     <body>
     <body>
         This resource is called <* httpWrite( getResourceName(getThisResource()) ) *>
         Этот ресурс называется <* httpWrite( getResourceName(getThisResource()) ) *>
     </body>
     </body>
<html>
<html>
</syntaxhighlight>
</syntaxhighlight>


There is a shorthand (in common with PHP and ASP) for this code, meaning that you can also write the above code as:
Имеется краткая альтернатива (совместно с PHP и ASP) этого кода, а это значит, что код выше можно также записать как:


<syntaxhighlight lang="lua">[html]
<syntaxhighlight lang="lua" lang="html">
<html>
<html>
     <body>
     <body>
         This resource is called <* = getResourceName(getThisResource()) *>
         Этот ресурс называется <* = getResourceName(getThisResource()) *>
     </body>
     </body>
<html>
<html>
</syntaxhighlight>
</syntaxhighlight>


Aside from HTTP functions, embedded Lua has access to the following environment variables that contain information about how the page was requested:
Отдельно от HTTP функций, встроенный Lua имеет доступ к следующим переменным среды, содержащим информацию про то, как была запрошена страница:
* table '''requestHeaders''': This is a table containing all the headers that were requested with the page. You can set returned headers using [[httpSetResponseHeader]].  
* table '''requestHeaders''': Эта таблица содержит все заголовки, которые были запрошены со страницей. Вы можете установить возвращаемые заголовки через использование [[httpSetResponseHeader]].  
* table '''form''': This is a table containing all the form data submitted to the page using HTTP POST combined with any variables passed in the querystring with HTTP GET.
* table '''form''': Эта таблица содержит все данные формы, переданные странице с использованием HTTP POST совмщенно с любыми переменными, переданными в строке запроса с HTTP GET.
* table '''cookies''': This is a table of all the cookies. You can modify cookies using [[httpSetResponseCookie]].
* table '''cookies''': Это таблица со всеми cookies. Вы можете редактировать cookies с использованием [[httpSetResponseCookie]].
* string '''hostname''': This is a string containing the IP address or hostname that requested the page.
* string '''hostname''': Это строка, содержащая IP адрес или имя хоста, запросившего страницу.
* string '''url''': This is the URL of the page.
* string '''url''': Это URL страницы.
* account '''user''': This is the account of the current user.
* account '''user''': Это аккаунт текущего пользователя.


It's important to note that parsed files are run in a separate virtual machine from the rest of your resource's code. As such, if you want to call a function in your resource's main code, you need to export the function and use the [[call]] function from your parsed file.
Важно заметить, что анализируемые файлы запущены в отдельной от остального кода вашего ресурса виртуальной машине. Следовательно, если вы хотите вызвать функцию из основного кода вашего ресурса, вам понадобится ее экспортировать и воспользоваться функцией [[call]] из анализируемого файла.


==Calls==
==Вызовы==
You can specify that certain exported functions in your resource are able to be called from the HTTP interface. All the SDKs (listed below) allow you to call these functions from a remote location.  
Вы можете указать, чтобы определенные экспортированные функции вашего ресурса могли быть вызваны через HTTP-интерфейс. Все SDK (указанные ниже) позволяют вам вызывать эти функции удаленно.  


To specify an exported http-accessible function, add the following to your meta.xml file:
Для указания экспортированной функции, доступной по http, добавьте в файл meta.xml следующее:
<syntaxhighlight lang="xml">
<syntaxhighlight lang="lua" lang="xml">
<export function='functionName' http='true' />
<export function='functionName' http='true' />
</syntaxhighlight>
</syntaxhighlight>


You can code your function just as you would any normal function, returning as many values as you want, including tables and resources and most importantly elements. You ''cannot'' however return other 'userdata' values such as [[xmlnode|xmlnodes]] or functions.
Вы можете писать свою функцию как и любую другую обычную, возвращать сколько вам угодно много значений, включия таблицы, ресурсы и, что более важно, элементы. Тем не менее вы ''не можете'' возвращать другие значения 'userdata' типа [[xmlnode|xmlnodes]] или функций.
 
===Протокол===
{{note_box|Вам не нужно этого знать за исключением случаев, если вы пишете свой собственный код HTTP-запроса. Можно просто воспользоваться одним из [[#SDK|SDK, указанных ниже]].}}
 
Вызовы выполняются через запрос ''<nowiki>http://<ваш IP>:<ваш порт>/<имя_ресурса>/call/<имя_экспортированной_функции></nowiki>'' с использованием HTTP POST. Тело запроса должно быть JSON массивом из аргументов для функции.
 
Запрос возвратит JSON-массив значений, возвращенных функцией как HTTP-ответ.


===Calls from the HTTP web interface===
Сервер поддерживает HTTP Basic идентификацию, вы можете конфигурировать доступ через ACL и встроенную систему аккаунтов.
Using calls is probably easiest from the web interface and can be done almost seamlessly.


First, add this to your meta.xml file:
===Вызовы из HTTP веб-интерфейса===
<syntaxhighlight lang="xml">
Вызовы, вероятно, наиболее легки из веб-интерфейса и могут выполняться практически без усилий.
 
Во-первых, добавьте в файл meta.xml следующее:
<syntaxhighlight lang="lua" lang="xml">
<include resource="ajax" />
<include resource="ajax" />
</syntaxhighlight>
</syntaxhighlight>


Secondly, add the following to the <head> section of the page you want to call from:
Во-вторых, в секцию <head> страницы, из который вы хотите производить вызов, добавьте следующее:
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua" lang="lua">
<* = call ( getResourceFromName("ajax"), "start", getResourceName(getThisResource()) ) *>
<* = exports.ajax:start(getResourceName(getThisResource())) *>
</syntaxhighlight>
</syntaxhighlight>


Finally, you can create a javascript block in your page and call your functions almost as if they were local. The only difference is that the calls are aysnchronous - you should specify a callback function as the last argument for your call. This is called when the function returns.
Наконец, вы можете создать на своей странице javascript-блок и вызывать свои функции практически так же, как если бы они были локальными. Единственное различие в том, что вызовы асинхронны - вам следует указывать callback-функцию последним аргументом для своего вызова. Она будет использоваться для возврата каких-либо значений основной функцией.


Here's a simple example.
Вот простой пример.


'''meta.xml'''
'''meta.xml'''
<syntaxhighlight lang="xml">
<syntaxhighlight lang="lua" lang="xml">
<meta>
<meta>
   <include resource="ajax" />
   <include resource="ajax" />
Line 92: Line 101:


'''code.lua'''
'''code.lua'''
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua" lang="lua">
function showChatMessage ( message )
function showChatMessage ( message )
     outputChatBox ( message )
     outputChatBox ( message )
Line 100: Line 109:


'''page.htm'''
'''page.htm'''
<syntaxhighlight lang="lua">[html]
<syntaxhighlight lang="lua" lang="html">
<html>
<html>
     <head>
     <head>
         <* = call ( getResourceFromName("ajax"), "start", getResourceName(getThisResource()) ) *>
         <* = exports.ajax:start(getResourceName(getThisResource())) *>
         <script type='text/javascript'>
         <script type='text/javascript'>
             function say() {
             function say() {
Line 109: Line 118:
                 showChatMessage ( message.value,  
                 showChatMessage ( message.value,  
                     function ( number ) {
                     function ( number ) {
                         // the function has been called and returned something
                         // функция была вызвана и что-то вернула
                         message.value = "The function returned " + number;
                         message.value = "Функция вернула " + number;
                     }
                     }
                 );
                 );
Line 122: Line 131:
</syntaxhighlight>
</syntaxhighlight>


You can see (fairly complex) examples of how this can be done in the resources ''resourcebrowser'', ''resourcemanager'' and ''webadmin''.
Вы можете видеть (довольно сложные) образцы того, как это можно сделать, в ресурсах ''resourcebrowser'', ''resourcemanager'' и ''webadmin''.
 
==Обезопашивание веб-интерфейса==
[[ACL]] предоставляет некоторое количество прав, которые могут влиять на то, какие файлы смогут быть доступны.
* general.http: Если выключен, никакие из http файлов не будут доступны (за исключением игровых клиентов)
* resource.'''ResourceName''': Если выключен, никакие из файлов ресурса не будут доступны
* resource.'''ResourceName'''.file.'''FileName''': Если выключен, файл с данным названием не будет доступен
* resource.'''ResourceName'''.function.'''FunctionName''': Если выключен, функцию невозможно будет вызвать
Они работают как и другие ACL права - вы можете их отключить для обычных пользователей и просто включить для группы Admin, или любой другой, которой вы пожелаете.


==SDK==
==SDK==
There are a number of so-called 'SDKs' available that allow you to interface with the server from other programming languages. With these you could (in theory) write whole gamemodes. In practice this is probably a bad idea, but it is useful for statistics and administration. The PHP SDK is the most developed version. Feel free to modify or create your own SDKs - if you do please send us a copy.
Доступно некоторое количество так называемых 'SDK', которые позволяют вам сообщаться с сервером через другие языки программирования. С их помощью вы (теоретически) можете писать целые игровые режимы. На практике, возможно, не очень хорошая идея, но это тем не менее является очень полезным для статистики и администрирования. PHP SDK - наиболее развитая версия. Не стесняйтесь модифицировать или создавать собственные SDK - если решитесь, пожалуйста, пришлите нам копию.


* [[Java SDK]]
* [[Java SDK]]
Line 131: Line 148:
* [[Perl SDK]]
* [[Perl SDK]]
* [[PHP SDK]]
* [[PHP SDK]]
* [[CSharp SDK|C# SDK]]


==See Also==
==Также смотрите==
[[callRemote]] - Allows game servers to call functions on PHP pages (with the PHP SDK) and on other game servers.
[[callRemote]] - Позволяет игровым серверам вызывать функции на PHP-страницах (с PHP SDK) и других игровых серверах.
[[Category:Scripting Concepts]]
[[Category:Scripting Concepts]]
[[en:Resource Web Access]]

Revision as of 11:40, 13 June 2012

Сервер 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 или функций.

Протокол

This template is no longer in use as it results in poor readability.

Вызовы выполняются через запрос 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) и других игровых серверах.

Retrieved from "https://wiki.multitheftauto.com/wiki/RU/Resource_Web_Access?oldid=31395"