Z-BlogPHP自定义API可以根据自己的需求创建和定制API接口,实现与博客系统的交互、数据操作以及开发自己的应用程序。使用API模块里的接口可以很方便的扩展出自定义的 API。本篇教程将以newapi插件为例,扩展出一个api模块并定义一个api命令。(本篇内容所用代码需要由主程序 1.7.1.2990 版本及更高版本实现)
一、创建插件
插件 id 假定为newapi,其include.php文件内容如下:
RegisterPlugin("newapi","ActivePlugin_newapi");
#newapi_RegAPI函数挂在Filter_Plugin_API_Extend_Mods接口上
function ActivePlugin_newapi() {
RegisterPlugin("newapi","ActivePlugin_newapi");
#newapi_RegAPI函数挂在Filter_Plugin_API_Extend_Mods接口上
function ActivePlugin_newapi() {
// ...
}
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里
# 直接在注册插件时操作
function ActivePlugin_newapi() {
// ...
ApiAddMod('newapi', __DIR__ . '/myapi.php'); // 实现文件以'newapi'为模块名插入进系统API里
}
# 直接在注册插件时操作
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');
#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');
}
#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() {
//在函数里完成 权限验证 接收参数 并 验证参数
return array('data' => $data);
//请注意:我们在示例里没有验证权限,只做了简单的返回数据
function api_newapi_helloworld() {
//在函数里完成 权限验证 接收参数 并 验证参数
$data = 'Hello world!';
return array('data' => $data);
//请注意:我们在示例里没有验证权限,只做了简单的返回数据
}
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');
//挂上接口
Add_Filter_Plugin('Filter_Plugin_API_VerifyCSRF_Skip', 'newapi_IgnoreCSRF');
//将newapi的helloworld加入进跳过验证数组
function newapi_IgnoreCSRF(&$array) {
$array[] = array('mod' => 'newapi', 'act' => 'helloworld');
}
//挂上接口
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模块下的
# 直接在注册插件时操作
function ActivePlugin_newapi() {
// ...
ApiAddAllowMod('newapi');//允许newapi模块下的所有api
ApiAddAllowMod('member', 'login');//允许member模块下的login
//开启白名单后,除了newapi模块和member模块下的login外,其它的api都不能访问!
ApiAddAllowMod('member', 'login');//取消允许member模块下的
}
# 直接在注册插件时操作
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都不能访问!
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都不能访问!
}
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
# 直接在注册插件时操作
function ActivePlugin_newapi() {
// ...
ApiAddDisallowMod('newapi', 'postdata');//禁用newapi模块下的postdata
ApiAddDisallowMod('system');//禁用system模块下所有的api
//开启黑名单后,没有在禁用范围里的api都可以被访问!
ApiRemoveDisallowMod('newapi', 'postdata');//取消禁用newapi模块下的postdata
}
# 直接在注册插件时操作
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都可以被访问!
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都可以被访问!
}
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 命令名称。
下面是返回的数据内容:
"runtime":{"time":"31.89","query":4,"memory":-1100}
{
"code":200,
"message":"OK",
"data":"Hello world!",
"error":null,
"runtime":{"time":"31.89","query":4,"memory":-1100}
}
{
"code":200,
"message":"OK",
"data":"Hello world!",
"error":null,
"runtime":{"time":"31.89","query":4,"memory":-1100}
}