ngrok客户端API

优质

小牛编辑

129浏览

2023-12-01

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": "",
}
}