SDK使用帮助

November 8, 2024About 6 min

SDK使用帮助

1. 概述

1.1. i2up API概述

i2UP对外开放的接口范围，同控制台页面具备的功能一致，和控制台调用的接口是同一套，没有差异；也就是说控制台上有的功能，都有对应接口，其他的就需要定制。

英方i2UP 控制台7.x及以上版本API整体采用RESTful风格，仅支持HTTPS调用；除GET请求外请求参数仅支持JSON格式；返回格式支持JSON（默认）、XML两种格式（在接口地址后面加上“.json” 、“.xml”即可）。

鉴权形式存在两种：一种是通过用户名和密码获取Token，简称Token认证；另一种是控制台上生成的accessKey和scretKey对用户进行认证，简称AK/SK认证。无论是哪种鉴权模式都需要做签名，签名可以通过配置文件进行控制（默认开启）。

1.2. API说明

1.2.1. 请求协议

i2up使用HTTPS协议。

1.2.2. 请求URL

API请求URL为：https://<控制台IP或者domain>:<控制机端口>/api/

控制机IP或者domain：指i2UP的控制台访问地址。

控制台端口：i2up里默认端口为58086，可以自行修改nginx的配置来更改。

API路由（path）：唯一资源标识部分（去掉统一前缀剩下的部分），对应接口文档（html apiref）中的URL部分，如果手动测试，需要手动补充/api/。

1.2.3. 请求方法（Method）

请求方法定义了如何与资源交互，常见的请求方法包括：

GET：从服务器获取数据。
POST：向服务器发送数据（通常用于创建新资源）。
PUT：更新服务器上的数据。
DELETE：从服务器删除数据。

通常情况下，GET只在URL中携带参数，POST的请求参数为JSON格式。

1.2.4. 请求头（Headers）

请求头包含关于请求的元数据，如认证信息、内容类型等。

如下是获取看板数据时的请求头：

1.2.5. 请求参数（Body）

请求参数也叫消息体，通常为JSON格式，具体参数说明见html版apiref。

1.2.6. API响应（Response）

API响应默认使用JSON格式。

i2up API返回的JSON格式说明如下：

ret：HTTP 错误码，正常情况下都为200，如果服务器内部错误，会返回500，可能的值：200，400，401，404，500，并不是接口实际的错误码。

msg：对返回错误的说明，产生的可能原因解释，正常情况下为空。

data：每个API返回的实际数据不同，需要参考html版的apiref。Data的JSON也包含两个常规的字段：

code：API执行返回的操作结果码，正常为0。

message：对操作结果码的说明，正常为空。

1.2.7. 示例

如下是登录认证API的详细说明：

请求协议：HTTPS
请求的URL为：https://172.20.16.1:58086/api/auth/token
请求的Method为：POST
请求参数（Body）为：

{
   "username": "admin",
   "pwd": "ignore the content",
   "_": "a16c02513d8b6"
}

请求响应值（Response）为：

{
   "ret": 200,
   "msg": "",
   "data": {
      "code": 0,
      "message": "",
      "token": "8bdb30f3e6c00cb21b7a6109c1896ca03c6421bf",
      "sso_token": "ignore the content",
      "refresh_token": "ignore the content"
   }
}

默认返回JSON数据：

可在接口地址末尾加上返回格式（xml）：

2. 接口调用说明

2.1. API调用流程

步骤：

创建鉴权对象Auth
选择认证方式：
- Token认证：通过登录i2up的用户名和密码创建Auth对象。
- AK/SK认证：通过i2up用户的AK(Access Key ID)和SK(Secret Access Key) 创建Auth对象。相对来说AK/SK认证安全性更高。一般推荐创建专门的用户，并授予合适的权限，用于API调用，以便于管理和审计。
创建业务对象
通过业务对象调用所需的方法，完成想要的操作。

2.2. Token认证

当使用Token认证时，需要通过登录i2up的用户名和密码创建Auth对象，并在创建业务对象时传递。

PHP代码示例：

$params = array(
    'username' => 'admin',
    'pwd' => 'Info1234',
    'cache_path' => 'd:/temp/', // 缓存token的路径
    'ip' => '172.20.16.10', // i2up服务器ip
);
$auth = new Auth($params);
$node = new Node($auth);
$arr = array(
    'node_uuid'=>'',
    'page'=>1,
    'limit'=>10,
    );
$res = $node->listRules($arr);
...

2.3. AK/SK认证

用AK/SK代替用户名和密码，获取用户Token，来完成Token认证，以减少AK在网络上传输的次数。

AK/SK的获取方法：登录i2up -> 点击标题栏里的用户名 -> 点击密钥管理 -> 点击新建

新建秘钥时，请妥善保存SecretKey（只在首次创建时才可见）。

PHP代码示例：

$params = array(
    'access_key' => '5uGoYvCLMk1mxb4KQqPgZdITz6sS2iOU',
    'secret_key' => 'T4vzNwV5reLEq9CfoKFc8mpk3YUd2PnhA1ZBgQlR',
    'ip' => '172.20.16.10', // i2up服务器ip
);
$auth = new Auth($params);
$node = new Node($auth);
$arr = array(
    'node_uuid'=>'',
    'page'=>1,
    'limit'=>10,
    );
$res = $node->listRules($arr);
...