客户端API - 《ngrok 中文文档》

ngrok客户端API

ngrok客户端API

ngrok客户端公开了一个REST API，它授予对以下各项的编程访问权限：

收集状态和指标信息
收集和重放捕获的请求
动态启动和停止隧道

基本URL和身份验证

Base URL	`http://127.0.0.1:4040/api`
Authentication	None

ngrok客户端API作为ngrok的本地Web检查接口的一部分公开。因为它在本地接口上提供，所以API没有身份验证。如果您覆盖配置文件中的web_addr，基本URL将会更改。

访问正在运行的ngrok客户端的根API资源

curl http://localhost:4040/api/

支持的内容类型

请求参数可以使用 application/x-www-form-urlencoded or application/json编码到API。确保您的客户机适当地设置请求的Content-Type头。 API返回的所有响应都是 application/json

版本控制和API稳定性

ngrok客户端API保证，除非调用者明确选择使用较新的版本，否则绝不会对API进行更改。呼叫者选择加入API的新版本的机制将在以后当有必要时被确定。不会选择加入的API的不间断更改示例包括以下内容。

增加新的资源
向现有资源添加新方法
在现有资源表示上添加新字段
修正错误，修改API以符合记录的行为

列出隧道

返回包含状态和指标信息的正在运行的隧道的列表。

Request

GET/api/tunnels

Response

Parameters

`tunnels`	所有正在运行的隧道的列表。有关每个隧道对象的参数的文档，请参阅隧道详细资源

示例响应

{
    "tunnels": [
        {
            "name": "command_line",
            "uri": "/api/tunnels/command_line",
            "public_url": "https://d95211d2.ngrok.io",
            "proto": "https",
            "config": {
                "addr": "localhost:80",
                "inspect": true,
            },
            "metrics": {
                "conns": {
                    "count": 0,
                    "gauge": 0,
                    "rate1": 0,
                    "rate5": 0,
                    "rate15": 0,
                    "p50": 0,
                    "p90": 0,
                    "p95": 0,
                    "p99": 0
                },
                "http": {
                    "count": 0,
                    "rate1": 0,
                    "rate5": 0,
                    "rate15": 0,
                    "p50": 0,
                    "p90": 0,
                    "p95": 0,
                    "p99": 0
                }
            }
        },
        ...
    ],
    "uri": "/api/tunnels"
}

启动隧道

动态地在ngrok客户端上启动一个新的隧道。请求主体参数与在配置文件中用于定义隧道的参数相同。

Request

POST/api/tunnels

Parameters

参数名称和行为与配置文件中定义的参数名称和行为相同。使用隧道定义部分作为配置参数及其行为的参考。

请求正文示例

{
    "addr": "22",
    "proto": "tcp",
    "name": "ssh"
}

Response

2201状态码与响应主体描述启动的隧道。请参阅关于响应对象的参数的文档的 Tunnel 详细信息资源

示例响应

{
    "name": "",
    "uri": "/api/tunnels/",
    "public_url": "tcp://0.tcp.ngrok.io:53476",
    "proto": "tcp",
    "config": {
        "addr": "localhost:22",
        "inspect": false,
    },
    "metrics": {
        "conns": {
            "count": 0,
            "gauge": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        },
        "http": {
            "count": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        }
    }
}

隧道细节

获取命名运行隧道的状态和指标

Request

GET/api/tunnels/:name

Response

示例响应

{
    "name": "command_line",
    "uri": "/api/tunnels/command_line",
    "public_url": "https://ac294125.ngrok.io",
    "proto": "https",
    "config": {
        "addr": "localhost:80",
        "inspect": true,
    },
    "metrics": {
        "conns": {
            "count": 0,
            "gauge": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        },
        "http": {
            "count": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        }
    }
}

停止隧道

停止正在运行的隧道

Request

DELETE/api/tunnels/:name

Response

204状态代码与空主体

列出捕获的请求

返回捕获用于检查的所有HTTP请求的列表。这将只返回仍在内存中的请求（ngrok在内存使用超过inspect_db_size时清除捕获的请求）)

Request

GET/api/requests/http

Query Parameters

`limit`	要返回的最大请求数
`tunnel_name`	过滤器仅请求给定的隧道名称

Example Request

curl http://localhost:4040/api/requests/http?limit=50

Response

`requests`	捕获的请求列表。请参阅请求对象上文档的捕获的请求详细资源资源

示例响应

{
    "uri": "/api/requests/http",
    "requests": [
        {
            "uri": "/api/requests/http/548fb5c700000002",
            "id": "548fb5c700000002",
            "tunnel_name": "command_line (http)",
            "remote_addr": "192.168.100.25",
            "start": "2014-12-15T20:32:07-08:00",
            "duration": 3893202,
            "request": {
                "method": "GET",
                "proto": "HTTP/1.1",
                "headers": {
                    "Accept": [
                        "*/*"
                    ],
                    "Accept-Encoding": [
                        "gzip, deflate, sdch"
                    ],
                    "Accept-Language": [
                        "en-US,en;q=0.8"
                    ],
                    "Connection": [
                        "keep-alive"
                    ],
                    "User-Agent": [
                        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36"
                    ],
                    "X-Original-Host": [
                        "c159663f.ngrok.io"
                    ]
                },
                "uri": "/favicon.ico",
                "raw": ""
            },
            "response": {
                "status": "502 Bad Gateway",
                "status_code": 502,
                "proto": "HTTP/1.1",
                "headers": {
                    "Content-Length": [
                        "1716"
                    ]
                },
                "raw": "",
            }
        },
        ...
    ]
}

重播捕获的请求

针对隧道的本地端点重复请求

Request

POST/api/requests/http

Parameters

`id`	重放请求的ID
`tunnel_name`	要播放请求的隧道的名称。如果未指定，请求将针对其记录的相同隧道播放

请求示例

curl -d "id=548fb5c700000002" http://localhost:4040/api/requests/http

Response

204状态代码与空主体

删除捕获的请求

删除所有捕获的请求

Request

DELETE/api/requests/http

Response

204 status code with no response body

捕获的请求详细信息

返回捕获的请求的元数据和原始字节。原始数据在JSON响应中是base64编码的。如果本地服务器尚未响应请求，响应response值可以为null。

Request

GET/api/requests/http/:request_id

Response

示例响应

{
    "uri": "/api/requests/http/548fb5c700000002",
    "id": "548fb5c700000002",
    "tunnel_name": "command_line (http)",
    "remote_addr": "192.168.100.25",
    "start": "2014-12-15T20:32:07-08:00",
    "duration": 3893202,
    "request": {
        "method": "GET",
        "proto": "HTTP/1.1",
        "headers": {
            "Accept": [
                "*/*"
            ],
            "Accept-Encoding": [
                "gzip, deflate, sdch"
            ],
            "Accept-Language": [
                "en-US,en;q=0.8"
            ],
            "Connection": [
                "keep-alive"
            ],
            "User-Agent": [
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36"
            ],
            "X-Original-Host": [
                "c159663f.ngrok.io"
            ]
        },
        "uri": "/favicon.ico",
        "raw": ""
    },
    "response": {
        "status": "502 Bad Gateway",
        "status_code": 502,
        "proto": "HTTP/1.1",
        "headers": {
            "Content-Length": [
                "1716"
            ]
        },
        "raw": "",
    }
}