# API文档
## 目录

 
## 准备工作
在你开始使用时需要将Multicraft面板的 "设置" => "控制面板设置" 里的

启用Multicraft API

设置为启用

你需要在每个需要访问API的用户的下面生成API KEY. 通过点击 "用户" 的 左边菜单 => "生成API密钥"  用户就可以通过API密钥来使用Multicraft API ,以此访问自己可以管理的服务器以及一些公用API,超级用户可以管理全部服务器.

 
## 简单开始
在Multicraft安装包下面的 "api" 文件夹里面,你可以找到名为 "

MulticraftAPI.php

" 的文件.他可以使你方便安全地操作Multicraft API,本API说的就是文件法

[译者注:这个看似是一个class,是一个很高深的,但是这个API已经详细解释了]

要使用此API文件可以将其和你的PHP文件(my.php)放置在一起, 比如,要获取服务器状态:

my.php代码

require('MulticraftAPI.php');//引用API文件,必须
$api = new MulticraftAPI('http://example.com/multicraft/api.php', 'demo', '#6nh%tX=ot$sBX');//生成Class,参数1:面板网址/api.php 参数2:用户名 参数3:API密钥
//前面的为之后的代码都必须要的
print_r($api->getServerStatus(1, true));//输出getServerStatus的返回,此函数之后会解释

 

调用参数"$api->getServerStatus(1, true);" 时会返回id为1的服务器参数 - 包含了当前在服务器内的玩家及其ID - 就像这样:

返回值

array(
    'success' => true,//用来判断是否成功调用到了API
    'errors' => array(),//错误信息数组
    'data' => array(
        'status' => 'online',//服务器在线状态
        'onlinePlayers' => '1',//在线玩家数
        'players' => array(//玩家数组
            0 => array(
                'ip' => '192.168.1.149',
                'id' => '12',
                'name' => 'Player'
            )
        )
        'maxPlayers' => '16'//最大玩家数
    )
)

[译者注开始]

所以我们可以这样来调用!

my.php

require('MulticraftAPI.php');
$api = new MulticraftAPI('http://example.com/multicraft/api.php', 'demo', '#6nh%tX=ot$sBX');
$ret=$api->getServerStatus(1, true);
if ($ret['success']==true){//判断API是否调用成功
    $dat=$ret['data'];
    echo '当前服务器状态'.$dat['status'];
echo '当前在线人数'.$dat['onlinePlayers'];
foreach ($player as $dat['players']){
    echo $player['name'].'的IP是'.$player['ip'];
}
}

这样大概没有问题吧

[译者注结束]
## 参数
所有参数都是普通的PHP变量，在下面的函数清单中应该是解释清楚了的。惟一允许传递数组的函数是“find”和“update”函数。
"find" and "update" 函数的使用方法是:

$api->findUsers('name', '=admin');

来寻找用户名是admin的

 

 

$api->findUsers(array('name', 'email'), array('test', '@example.com'));

来查找用户名里含有test且邮箱有example.com的

 
## 返回值
所有的返回值都是下面的格式:

array(
    'success' => true,//是否执行成功 [true/false]
    'errors' => array(),//错误信息
    'data' => array()//返回数据
)

假如执行成功的话success会是true且data会(不一定)返回东西
假如失败的话 success会是 false, data是空数组,errors会包含错误信息

 
## 例子
寻找匹配用户(邮箱匹配):

$response = $api->findUsers('email', '='.$email);
if ($response['success'])
{
    $user = $response['data']['Users'];
    foreach ($user as $id=>$name)
        echo 'Name: '.$name.', ID: '.$id.'<br/>';
}

寻找匹配用户(邮箱模糊查询):

$response = $api->findUsers('email', $partialEmail);
if ($response['success'])
{
    $user = $response['data']['Users'];
    foreach ($user as $id=>$name)
        echo 'Name: '.$name.', ID: '.$id.'<br/>';
}

创建服务器:

$api->createServer('New Minecraft Server');

创建服务器在指定daemon:

$api->createServerOn($daemonId);

修改服务器设置:

$response = $api->updateServer($serverId, array(
        'memory',
        'ip',
        'port',
    ),
    array(
        $newMemory,
        $newIp,
        0,
    )
);

允许用户修改jar文件和玩家数:

$response = $api->updateServerConfig($serverId, array(
        'user_jar',
        'user_players',
    ),
    array(
        true,
        true,
    )
);

移动服务器到另一个Daemon:

$response = $api->moveServer($serverId, $daemonId);

 
## Functions
[译者注]

下面的参数译者也翻译了哦,可能有些地方不妥当,请见谅

这个ARRAY只是data里面的array哦,请特别注意!

函数介绍 返回值(data)
### 用户类
listUsers()

列出用户列表		 
array (
  'Users' => 
  array (
    1 => 'admin',
  ),
)
findUsers(参数, 值)

寻找用户(看上面的示例)		 
array (
  'Users' => 
  array (
    2 => 'tester',
    3 => 'testUser2',
  ),
)
getUser(用户id)

获取用户信息		 
array (
  'User' => 
  array (
    'id' => '1',//用户ID
    'name' => 'admin',//用户名
    'email' => 'admin@localhost',//邮箱
    'global_role' => 'none',//权限
  ),
)
getCurrentUser() (2.0.0)

获取当前用户信息		 
array (
  'User' => 
  array (
    'id' => '1',//用户ID
    'name' => 'admin',//邮箱
    'email' => 'admin@localhost',//邮箱
    'global_role' => 'none',//权限
  ),
)
updateUser(用户id, 参数, 要更改的值)

更新用户信息		 
array (
)
createUser(用户名, 邮箱, 密码)

创建用户		 
array (
  'id' => 2,
)
deleteUser(用户id)

删除用户id		 
array (
)
getUserRole(用户ID, 服务器ID)

获取用户在服务器ID的权限		 
array (
  'role' => 'owner',//权限
)
setUserRole(用户ID, 服务器ID,权限)

设置用户管理服务器ID的权限		 
array (
)
getUserFtpAccess(用户ID,服务器ID)

获取用户访问FTP的资格		 
array (
  'mode' => 'rw',
)
setUserFtpAccess(用户ID, 服务器ID, 权限)

设置用户访问FTP的权限		 
array (
)
getUserId(用户名)

根据名称取用户ID		 
array (
  'id' => 3,
)
validateUser(用户名, 密码) (2.0.0)

验证用户		 
array (
)
generateUserApiKey(用户ID) (2.0.0)

生成用户API密钥		 
array (
    [api_key] => 123abc
)
getUserApiKey(用户ID) (2.0.0)

获取用户API密钥		 
array (
    [api_key] => 123abc
)
removeUserApiKey(用户ID) (2.0.0)

删除用户API密钥		 
array (
)
### 玩家类
listPlayers(服务器ID)

列出玩家		 
array (
  'Players' => 
  array (
    2 => 'Test_Player2',//玩家名
  ),
)
findPlayers(服务器ID, 参数,值)[译者注:可能参数是ip,name之类的吧]

寻找玩家,和寻找用户异曲同工		 
array (
  'Players' => 
  array (
    1 => 'Test_Player',
  ),
)
getPlayer(玩家ID)

获取玩家		 [译者注:官网也没写诶]
updatePlayer(id, field, value)

更新玩家信息		 
array (
)
createPlayer(server_id, name)

创建玩家		 
array (
  'id' => 2,
)
deletePlayer(id)

删除玩家		 
array (
)
assignPlayerToUser(player_id, user_id)

转换玩家成用户		 
array (
)
### 指令类
listCommands(server_id)

列举命令(Multicraft)		 
array (
  'Commands' => 
  array (
    18 => 'Test_Command',
  ),
)
findCommands(server_id, field, value)

寻找命令(Multicraft)		 
array (
  'Commands' => 
  array (
    18 => 'Test_Command',
  ),
)
getCommand(id)

获取命令
updateCommand(id, field, value)

修改指令		 
array (
)
createCommand(server_id, name, role, chat, response, run)

生成指令		 
array (
  'id' => 18,
)
deleteCommand(id)

删除指令		 
array (
)
### 服务器类
listServers()

列出服务器		 
array (
  'Servers' => 
  array (
    3 => 'Minecraft Server',
  ),
)
findServers(field, value)

寻找服务器		 
array (
  'Servers' => 
  array (
    3 => 'Minecraft Server',
  ),
)
listServersByConnection(connection_id)

在连接上寻找服务器		 
array (
  'Servers' => 
  array (
    3 => 'Minecraft Server',
  ),
)
listServersByOwner(user_id)

根据所有者显示服务器		 
array (
  'Servers' => 
  array (
    3 => 'Minecraft Server',
  ),
)
getServer(id)

获取服务器详细信息		 
array (
  'Server' => 
  array (
    'id' => '1',
    'name' => 'Test Server',
    'ip' => '',
    'port' => '25565',
    'dir' => 'server1',
    'world' => '',
    'players' => '8',
    'memory' => '0',
    'start_memory' => '0',
    'jarfile' => '',
    'autostart' => '0',
    'default_level' => '10',
    'daemon_id' => '1',
    'announce_save' => '1',
    'kick_delay' => '3000',
    'suspended' => '0',
  ),
)
updateServer(id, field, value)

修改服务器设置		 
array (
)
createServerOn(daemon_id = 0, no_commands = 0, no_setup_script = 0)

创建服务器在Daemin		 
array (
  'id' => 1,
)
createServer(name = '', port = 0, base = '', players = 0, no_setup_script = 0)

创建服务器		 
array (
  'id' => 1,
)
suspendServer(id, stop = 1)

停止服务器		 
array (
)
resumeServer(id, start = 1)

恢复服务器		 
array (
)
deleteServer(id, delete_dir = 'no', delete_user = 'no')

删除服务器		 
array (
)
getServerStatus(id, player_list = 0)

获取服务器状态		 
array (
  'status' => 'online',
  'onlinePlayers' => 0,
  'players' => 
  array (
  ),
  'maxPlayers' => '8',
)
getServerOwner(server_id)

获取服务器所有者		 
array (
  'user_id' => 2,
)
setServerOwner(server_id, user_id)

设置服务器所有者		 
array (
)
getServerConfig(id)

获取服务器配置		 
array (
  'ServerConfig' => 
  array (
    'server_id' => '1',
    'ip_auth_role' => 'guest',
    'give_role' => 'mod',
    'tp_role' => 'mod',
    'summon_role' => 'mod',
    'chat_role' => 'user',
    'user_jar' => '0',
    'user_ftp' => '0',
    'visible' => '1',
    'user_schedule' => '1',
  ),
)
updateServerConfig(id, field, value)

修改服务器设置		 
array (
)
startServerBackup(id)

开始备份服务器		 
array (
)
getServerBackupStatus(id)

获取服务器备份进度		 
array (
  'status' => 'running',
  'time' => '0',
  'message' => '[World: world] ',
  'file' => '/home/minecraft/multicraft/servers/server1/world.zip',
  'ftp' => '192.168.1.75:21',
)
startServer(id)

开启服务器		 
array (
)
stopServer(id)

停止服务器		 
array (
)
restartServer(id)

重启服务器		 
array (
)
killServer(id) (2.0.0)

强制结束服务器		 
array (
)
startAllServers()

开启所有服务器		 
array (
  '[1]success' => true,
  '[1]data' => 
  array (
  ),
  '[1]error' => false,
)
stopAllServers()

暂停所有服务器		 
array (
  '[1]success' => true,
  '[1]data' => 
  array (
  ),
  '[1]error' => false,
)
restartAllServers()

重启所有服务器		 
array (
  '[1]success' => true,
  '[1]data' => 
  array (
  ),
  '[1]error' => false,
)
killAllServers() (2.0.0)

强制结束所有服务器		 
array (
  '[1]success' => true,
  '[1]data' => 
  array (
  ),
  '[1]error' => false,
)
sendConsoleCommand(server_id, command)

发送控制台指令		 
array (
)
sendAllConsoleCommand(command)

发送命令道全部服务器		 
array (
  '[1]success' => true,
  '[1]data' => 
  array (
  ),
  '[1]error' => false,
)
runCommand(server_id, command_id, run_for = 0)

运行命令		 
array (
)
getServerLog(id)

获取服务器日志		 
array (
  0 => 
  array (
    'line' => '/Loading Minecraft instance properties/',
  ),
)
clearServerLog(id)

清理服务器日志		 
array (
)
getServerChat(id)

获取服务器聊天
clearServerChat(id)

清除聊天记录		 
array (
)
sendServerControl(id, command) (2.0.0)

发送给所有服务器		 
array (
)
getServerResources(id) (2.0.0)

获取服务器资源使用情况		 
array (
    [cpu] => 0
    [memory] => 0
)
moveServer(server_id, daemon_id) (2.0.0)

移动服务器		 
array (
)
### Daemon functions
listConnections() 
array (
  'Daemons' => 
  array (
    1 => '',
  ),
)
findConnections(field, value) 
array (
  'Daemons' => 
  array (
    1 => '',
  ),
)
getConnection(id)
removeConnection(id) 
array (
)
getConnectionStatus(id)
getConnectionMemory(id, include_suspended = 0) 
array (
  'total' => 2048,
  'used' => 1024,
)
getStatistics(daemon_id = 0, include_suspended = 0) (2.0.0) 
array (
    [daemons] => 1
    [daemon_memory] => 2048
    [servers] => 1
    [players] => 8
    [assigned_memory] => 256
)
### Settings functions
listSettings() 
array (
  'Settings' => 
  array (
    'dbVersion' => '5',
    'updateChecks' => '1',
    'anonStats' => '1',
  ),
)
getSetting(key) 
array (
  'Setting' => 
  array (
    'key' => 'updateChecks',
    'value' => '1',
  ),
)
setSetting(key, value) 
array (
)
deleteSetting(key) 
array (
)
### Schedule functions
listSchedules(server_id) 
array (
  'Schedules' => 
  array (
    1 => 'test schedule',
    2 => 'Test schedule 2',
  ),
)
findSchedules(server_id, field, value) 
array (
  'Schedules' => 
  array (
    1 => 'test schedule',
    2 => 'Test schedule 2',
  ),
)
getSchedule(id)
updateSchedule(id, field, value) 
array (
)
createSchedule(server_id, name, ts, interval, cmd, status, for) 
array (
  'id' => 1,
)
deleteSchedule(id) 
array (
)
### Database functions
getDatabaseInfo(server_id) (2.0.0) 
array (
    [host] => localhost
    [name] => mctemp_1
    [username] => mctemp_1
    [password] => 123abc
    [link] => 
)
createDatabase(server_id) (2.0.0) 
array (
    [host] => localhost
    [name] => mctemp_1
    [username] => mctemp_1
    [password] => 123abc
    [link] => 
)
changeDatabasePassword(server_id) (2.0.0) 
array (
    [host] => localhost
    [name] => mctemp_1
    [username] => mctemp_1
    [password] => 456def
    [link] => 
)
deleteDatabase(server_id) (2.0.0) 
array (
)