自定义 API

使用 API 模块里的接口可以很方便的扩展出自定义的 API

本篇以newapi插件为例，扩展出一个api模块并定义一个api命令。

创建插件

插件 id 假定为newapi，其include.php文件内容如下

RegisterPlugin("newapi","ActivePlugin_newapi");

#newapi_RegAPI函数挂在Filter_Plugin_API_Extend_Mods接口上
function ActivePlugin_newapi() {
    // ...
}

挂上接口，插入 API 模块文件

把myapi.php这个api文件模块插入进 API 系统，一个api文件模块内可包含多个api(act)

新版（1.7.3 以后）写法

# 直接在注册插件时操作
function ActivePlugin_newapi() {
    // ...
    ApiAddMod('newapi', __DIR__ . '/myapi.php'); // 实现文件以'newapi'为模块名插入进系统API里
}

老版写法

#include.php里的newapi_RegAPI函数实现

function ActivePlugin_newapi() {
    Add_Filter_Plugin('Filter_Plugin_API_Extend_Mods', 'newapi_RegAPI');
}

#将插件目录下的myapi.php这个API实现文件以'newapi'为模块名插入进系统API里
function newapi_RegAPI() {
    return array('newapi' => __DIR__ . '/myapi.php');
}

定义 API 文件模块

在myapi.php这个自定义 api 模块里定义了一个 api 叫helloworld

api函数名称是有规律的，必须是api_打头，注册模块名居中，加一个_，再由api命令名称居末尾组合而成，这样 API 系统才能路由到此函数

function api_newapi_helloworld() {
    //在函数里完成 权限验证 接收参数 并 验证参数
    $data = 'Hello world!';
    return array('data' => $data);
    //请注意：我们在示例里没有验证权限，只做了简单的返回数据
}

在使用 POST 方式提交数据到 api，必须在提交时传入 api 登录成功后返回的token（设 Authorization 请求头为'Bearer token 值'，抑或是在 POST 传入 input 表单，name 为'token'，value 为 token 值）

如果系统在ApiTokenVerify()里验证成功，就跳过 crsf_token 检查！否则 POST 提交会失败！

如果上述都不能实现，还可以通过挂 Filter_Plugin_API_VerifyCSRF_Skip 这个接口，将该 mod 的 api 加入跳过 CSRF 验证的数组中，代码如下：

//挂上接口
Add_Filter_Plugin('Filter_Plugin_API_VerifyCSRF_Skip', 'newapi_IgnoreCSRF');

//将newapi的helloworld加入进跳过验证数组
function newapi_IgnoreCSRF(&$array) {
  $array[] = array('mod' => 'newapi', 'act' => 'helloworld');
}

API 模块的白名单和黑名单

$mods_allow 白名单请慎用，启用白名单后，不在白名单的 mod 都将被拒绝

如果只想关闭某些模块，只需要对$mods_disallow 黑名单进行添加

白名单示范（新版 1.7.3 以后）：

# 直接在注册插件时操作
function ActivePlugin_newapi() {
    // ...
    ApiAddAllowMod('newapi');//允许newapi模块下的所有api
    ApiAddAllowMod('member', 'login');//允许member模块下的login
    //开启白名单后，除了newapi模块和member模块下的login外，其它的api都不能访问！

    ApiAddAllowMod('member', 'login');//取消允许member模块下的
}

白名单示范（老版）：

Add_Filter_Plugin('Filter_Plugin_API_CheckMods', 'newapi_CheckMods');

function newapi_CheckMods(&$mods_allow, &$mods_disallow) {
    $mods_allow[] = array('newapi' => '');//允许newapi模块下的所有api
    $mods_allow[] = array('member' => 'login');//允许member模块下的login
    //开启白名单后，除了newapi模块和member模块下的login外，其它的api都不能访问！
}

黑名单示范（新版 1.7.3 以后）：

# 直接在注册插件时操作
function ActivePlugin_newapi() {
    // ...
    ApiAddDisallowMod('newapi', 'postdata');//禁用newapi模块下的postdata
    ApiAddDisallowMod('system');//禁用system模块下所有的api
    //开启黑名单后，没有在禁用范围里的api都可以被访问！

    ApiRemoveDisallowMod('newapi', 'postdata');//取消禁用newapi模块下的postdata
}

黑名单示范（老版）：

Add_Filter_Plugin('Filter_Plugin_API_CheckMods', 'newapi_CheckMods');

function newapi_CheckMods(&$mods_allow, &$mods_disallow) {
    $mods_disallow[] = array('newapi' => 'postdata');//禁用newapi模块下的postdata
    $mods_disallow[] = array('system' => '');//禁用system模块下所有的api
    //开启黑名单后，没有在禁用范围里的api都可以被访问！
}

访问 API

API 访问地址:

https://测试网站/zb_system/api.php?mod=newapi&act=helloworld

其中，mod参数是模块名，act参数是 api 命令名称

下面是返回的数据内容：

{
    "code":200,
    "message":"OK",
    "data":"Hello world!",
    "error":null,
    "runtime":{"time":"31.89","query":4,"memory":-1100}
}

本篇内容所用代码需要由主程序 1.7.1.2990 版本及更高版本实现