# 快速开始

# 工作原理介绍

续断内网穿透（下简称 “续断”）提供一系列 RESTful API ，让您可以快速管理续断客户端和隧道。您可以使用 cURL 或在您的程序里通过 HTTP Client 调用。我们在每一个 API 说明里均附有 cURL 调用的示例。

首先以 http 隧道为例，简单介绍一下续断的工作原理，方便您更好地理解如何调用本 API。

当外部应用（如浏览器）通过续断隧道访问您内网服务时：

1. 请求先由续断的中转服务器转发到 绑定的客户端 ；
2. 转发时会根据 绑定的隧道授权 信息，调整转发速率（带宽值）和转发频率（并发连接数）；
3. 客户端把请求转发到本地服务，获取资源并原路返回；
4. 浏览器显示出内容。

因此，在新建隧道时，需要先安装好续断客户端和拥有续断隧道授权。

哲西云：
安装客户端快速入口

哲西云测试平台：
安装客户端快速入口

# API 使用方法

# 接下来，以一个常见的例子演示如何使用续断 API

手工安装完成客户端之后，使用接口购买 1Mbps，50 并发，7 天的授权。
新建隧道，映射安装客户端的电脑的远程桌面服务 3389 端口。（如果是 Linux 则映射 ssh 的 22 端口）

我们提供的保姆级教程，会详细说明每一步的操作。 教程中涉及购买授权等操作，需要从您的帐户余额中扣除一定的金额 ，请登录 哲西云 或 哲西云测试平台 先行充值余额（ 测试平台中，您的订单系统会自动为您支付，不会产生任何真实费用 ）。为更方便理解，在快速入门的最后，能找到 完整的示例代码 。

# CMD
curl.exe -XPOST "{{location}}/api/v2/mapping/tunnel?apikey=您的apikey" ^
-H "Content-Type: application/json" ^
-d "{\"ip\": \"127.0.0.1\"}"

# PowerShell
curl.exe -XPOST "{{location}}/api/v2/mapping/tunnel?apikey=您的apikey" `
-H "Content-Type: application/json" `
-d "{\`"ip\`": \`"127.0.0.1\`"}"

新建隧道需要经过以下步骤：

1. 获取（生成）您的 apikey ，调用 API 时均需要使用；
2. 调用 获取客户端信息 API ，传入内网 IP、MAC 地址和备注名等参数，拿到绑定隧道的 客户端ID ；
3. 调用 获取隧道授权 API ，传入授权类型、带宽和有效期等参数，拿到可用的 隧道授权ID ，没有可用授权则需要购买；
4. 调用 新建隧道 API ，传入上面 2 个步骤得到的 ID，再加上隧道的其他像协议、内网 IP、内网端口等参数；
5. 隧道创建成功。

# 1.获取（生成）您的 APIKEY

调用 API 时，系统会通过 apikey 识别用户身份和权限。您需要先登录到 哲西云 或 哲西云测试平台 ，在右上角用户名处的弹出菜单，进入到 账户信息 页面，然后点击 API 配置中的 立即生成 按钮生成 apikey，如下图：

apikey 是一种用户身份凭据，免去用户调用 API 时输入账号名和密码的麻烦。测试平台与正式环境相互独立，所生成的 apikey 并不通用，使用前请先确认。因拥有相同的用户权限，生成后，用户需谨慎使用，请勿外发！

# 2.获取客户端 ID

续断内网穿透是通过用户本地安装的一个客户端进行数据转发，这里假设用户已经安装好续断客户端，并且该客户端处于正常运行状态。如未安装客户端，请参考 安装客户端 或 预装客户端 进行安装。

在终端*中输入以下命令，需要把命令中的 您的apikey 替换成第一步中获取到的 apikey 。

Windows:

通常指 cmd 或 PowerShell ，系统可能没有预装 cURL，请自行安装。

macOS:

通常指 终端（Terminal） 或 zsh 。

Linux:

通常指 终端（Terminal） 或 bash 。

curl -XGET '{{location}}/api/v2/machine/list?apikey=您的apikey'

返回结果：

{
    "error": 0,
    "data": [
            "id": "客户端ID",
            "name": "DESKTOP-xxxxxx",
            "remark": "",
            "os": "Windows 10 Pro",

data 中的 id 就是我们需要客户端 ID，记下来备用。一般的使用场景 data 中只包含一个 JSON对象 ，即只返回符合条件的第一个客户端的信息。

如果用户在安装客户端时指定客户端备注，或在 Web 控制台上对该客户端进行备注，可使用 remark 参数指定要获取的客户端，如：

curl -XGET '{{location}}/api/v2/machine/list?apikey=您的apikey&remark=测试1'

返回结果：

{
    "error": 0,
    "data": [
            "id": "客户端ID",
            "name": "DESKTOP-xxxxxx",
            "remark": "测试1",
            "os": "Windows 10 Pro",

更多参数说明，请阅读 获取客户端信息 。

# 3.获取隧道授权 ID

获取 1Mbps，50 并发，7 天的授权。
（假设今天是 2021-09-01）

在终端中输入以下命令，需要把命令中的 您的apikey 替换成第一步中获取到的 apikey 。

curl -XGET '{{location}}/api/v2/mapping/valid?apikey=您的apikey&tunnelType=0&bandwidth=1&concurrency=50&expired_at=2021-09-08'

如果您是首次调用 获取隧道授权 API，会返回以下结果：

{
    "error": 0,
    "data": []

上面的 data 为空，表示您的帐户中没有符合条件的隧道授权，需要先调用 购买隧道授权 API 进行购买，购买示例如下：

（调用购买/升级接口所需金额将从帐户余额中扣除，请先充值，保证余额充足）

curl -XGET '{{location}}/api/v2/order/tunnel?apikey=您的apikey&bandwidth=1&concurrency=50&expired_at=2021-09-08'

返回结果：

{
    "error": 0,
    "data": {
        "id": "隧道授权ID",
        "cost": 183 // 本次消费1.83元

若您已购买过隧道授权，且授权符合查询符合条件，上面调用 获取隧道授权 API 时，会得到如下返回结果：

{
    "error": 0,
    "data": [
            "id": "隧道授权ID",
            "type": 0,
            "bandwidth": 1,
            "concurrency": 50,
            "expiredAt": "2021-09-09T07:40:12.000Z",

更多参数说明，请阅读 获取隧道授权 。

# 4.新建隧道

目前为止，我们已获得：

1. 客户端 ID；
2. 1Mbps，50 并发，7 天的隧道授权 ID；

接着调用 新建隧道 API ，映射内网 Windows 电脑 192.168.1.111 远程桌面服务 3389 端口。

在终端中输入以下命令，需要把命令中的 您的apikey 替换成第一步中获取到的 apikey 。

curl -XPOST '{{location}}/api/v2/mapping/tunnel?apikey=您的apikey' \
    -H 'Content-Type: application/json' \
    -d '{
            "name": "隧道名称",
            "machineID": "步骤2得到的客户端ID",
            "templet": "步骤3得到的隧道授权ID",
            "type": "0",
            "ip": "192.168.1.111",
            "port": "3389"

返回结果：

{
    "error": 0,
    "data": {
        "id": "xxxxxxxx-0049-11ec-8549-85142dbb7e3e",
        "domain": "ihxxx.51xd.tech",
        "port": 46600

返回值说明：

• id
  新创建的隧道的 ID
• domain
  系统随机分配的外网访问域名
• port
  系统随机分配的外网访问端口

更多参数说明，请阅读 新建隧道 。

接下来，我们可以另一台装有 Windows 系统的电脑上，启动远程桌面程序（mstsc.exe），输入 domain : port ，本例中是 ihxxx.51xd.tech:46600 ，如下图，即可发起远程控制：

至此，隧道创建成功！

# 完整代码示例

手工安装完成客户端之后，使用接口购买 1Mbps，50 并发，7 天的授权。
新建隧道，映射内网 Windows 电脑 192.168.1.111 远程桌面服务 3389 端口。（如果是 Linux 则映射 ssh 的 22 端口）
（假设今天是 2021-09-01）

# NodeJS - Axios

示例中忽略了错误处理，实际使用请自行处理

import axios from "axios";
const httpClient = axios.create({
    baseURL: "{{location}}",
    params: {
        apikey: "您的apikey",
});
// 获取客户端信息
const { data: clientRes } = await httpClient("/api/v2/machine/list", {
    params: {
        remark: "",
});
if (clientRes.current === 0) throw new Error("没有可用的客户端");
const clientID = clientRes.data[0].id;
console.log(`客户端ID：${clientID}`);
// 获取授权信息
const { data: templetRes } = await httpClient("/api/v2/mapping/valid", {
    params: {
        tunnelType: 0,
        bandwidth: 1,
        concurrency: 50,
        expired_at: "2021-09-08 00:00:00",
});
let templetID = "";
if (templetRes.current === 0) {
    // 没有可用隧道授权，直接购买
    const { data: orderRes } = await httpClient("/api/v2/order/tunnel", {
        params: {
            bandwidth: 1,
            concurrency: 50,
            expired_at: "2021-09-08 00:00:00",
    });
    if (orderRes.error === 0) templetID = orderRes.data.id;
} else templetID = templetRes.data[0].id;
if (templetID === "") throw new Error("没有可用的隧道授权");
console.log(`隧道授权ID：${templetID}`);
// 创建隧道
const { data } = await httpClient.post("/api/v2/mapping/tunnel", {
    name: "演示隧道",
    machineID: clientID,
    templet: templetID,
    type: 0,
    ip: "192.168.1.111",
    port: "3389",
});