Module ngx_http_api_module

ngx_http_api_module模块(1.13.3)提供 REST API，用于访问各种状态信息，动态配置上游服务器组以及管理key-value pairs，而无需重新配置 nginx。

Note

该模块取代了ngx_http_status_module和ngx_http_upstream_conf_module模块。

使用PATCH或POST方法时，请确保有效载荷不超过buffer size以读取客户端请求正文，否则，可能会返回 413(请求实体太大)错误。

Note

此模块可作为commercial subscription的一部分使用。

Example Configuration

http {
    upstream backend {
        zone http_backend 64k;

        server backend1.example.com weight=5;
        server backend2.example.com;
    }

    proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m;

    server {
        server_name backend.example.com;

        location / {
            proxy_pass  http://backend;
            proxy_cache cache_backend;

            health_check;
        }

        status_zone server_backend;
    }

    keyval_zone zone=one:32k state=one.keyval;
    keyval $arg_text $text zone=one;

    server {
        listen 127.0.0.1;

        location /api {
            api write=on;
            allow 127.0.0.1;
            deny all;
        }
    }
}

stream {
    upstream backend {
        zone stream_backend 64k;

        server backend1.example.com:12345 weight=5;
        server backend2.example.com:12345;
    }

    server {
        listen      127.0.0.1:12345;
        proxy_pass  backend;
        status_zone server_backend;
        health_check;
    }
}

所有 API 请求都在 URI 中包含受支持的 API version。具有此配置的 API 请求示例：

http://127.0.0.1/api/6/
http://127.0.0.1/api/6/nginx
http://127.0.0.1/api/6/connections
http://127.0.0.1/api/6/http/requests
http://127.0.0.1/api/6/http/server_zones/server_backend
http://127.0.0.1/api/6/http/caches/cache_backend
http://127.0.0.1/api/6/http/upstreams/backend
http://127.0.0.1/api/6/http/upstreams/backend/servers/
http://127.0.0.1/api/6/http/upstreams/backend/servers/1
http://127.0.0.1/api/6/http/keyvals/one?key=arg1
http://127.0.0.1/api/6/stream/
http://127.0.0.1/api/6/stream/server_zones/server_backend
http://127.0.0.1/api/6/stream/upstreams/
http://127.0.0.1/api/6/stream/upstreams/backend
http://127.0.0.1/api/6/stream/upstreams/backend/servers/1

Directives

Syntax:	`api [write=on\|off];`
Default:	—
Context:	`location`

打开周围位置的 REST API 接口。可以访问此位置limited。

write参数确定 API 是只读的还是读写的。默认情况下，API 是只读的。

所有 API 请求都应在 URI 中包含受支持的 API 版本。如果请求 URI 等于位置前缀，则返回支持的 API 版本列表。当前的 API 版本是“ 6”。

请求行中的可选“ fields”参数指定将输出所请求对象的哪些字段：

http://127.0.0.1/api/6/nginx?fields=version,build

Syntax:	`status_zone zone;`
Default:	—
Context:	`server` , `location` , `if in location`

该指令出现在 1.13.12 版中。

启用对指定的zone中的虚拟http或stream服务器状态信息的收集。多个服务器可以共享同一区域。

从 1.17.0 开始，可以按照location收集状态信息。特殊值off禁用嵌套位置块中的统计信息收集。注意，统计是在处理结束的位置的上下文中收集的。如果在请求处理期间发生internal redirect，它可能与原始位置不同。

Compatibility

/stream/limit_conns/数据已添加到version 6.
/http/limit_conns/数据已添加到version 6.
/http/limit_reqs/数据已添加到version 6.
key-value对的“ expire”参数可以是set或changed，因为version是 5.
/resolvers/数据已添加到version 5.
/http/location_zones/数据已添加到version 5.
nginx 错误对象的path和method字段已在version 4 中删除。这些字段在较早的 api 版本中 continue 存在，但显示为空值。
/stream/zone_sync/数据已添加到version 3 中。
drain参数已添加到version 2 中。
/stream/keyvals/数据已添加到version 2 中。

Endpoints

/

Supported methods:
GET-返回根端点的列表

返回根端点的列表。

Possible responses:

200 -成功，返回字符串数组
- 404 -未知版本(UnknownVersion)，返回Error

/nginx

Supported methods:
GET-Nginx 运行实例的返回状态

返回 nginx 版本，内部版本名称，地址，配置重载次数，主进程和工作进程的 ID。

Request parameters:

fields(string，可选)
- 限制将输出 nginx 运行实例的哪些字段。

Possible responses:

200 -成功，返回nginx
- 404 -未知版本(UnknownVersion)，返回Error

/processes

Supported methods:
GET-返回 nginx 进程状态

返回异常终止和重新生成的子进程的数量。

Possible responses:

200 -成功，返回Processes
- 404 -未知版本(UnknownVersion)，返回Error
DELETE-重置 nginx 进程统计信息

重置异常终止和重生的子进程的计数器。

Possible responses:

204 -成功
- 404 -未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/connections

Supported methods:
GET-返回客户端连接统计信息

返回客户端连接的统计信息。

Request parameters:

fields(string，可选)
- 限制将输出连接统计信息的哪些字段。

Possible responses:

200 -成功，返回Connections
- 404 -未知版本(UnknownVersion)，返回Error
DELETE-重置客户端连接统计信息

重置接受和删除的客户端连接的统计信息。

Possible responses:

204 -成功
- 404 -未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/slabs/

Supported methods:
GET-所有平板的 return 状态

使用平板分配器返回每个共享内存区域的平板状态。

Request parameters:

fields(string，可选)
- 限制将输出平板区域的哪些字段。如果“ fields”值为空，则仅输出区域名称。

Possible responses:

200 -成功，为所有平板返回“ 与平板分配器共享的内存区域”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/slabs/

所有方法共有的参数：
slabZoneName(string，为必填项)
- 使用平板分配器的共享内存区域的名称。

Supported methods:

GET-平板的返回状态

使用平板分配器返回特定共享内存区域的平板状态。

Request parameters:

fields(string，可选)
- 限制将输出平板区域的哪些字段。

Possible responses:

200 -成功，返回与平板分配器共享的内存区域
- 404 -未找到平板(SlabNotFound)，未知版本(UnknownVersion)，返回Error
DELETE-重置平板统计

重置每个内存插槽的“ reqs”和“ fails”度量。

Possible responses:

204 -成功
- 404 -未找到平板(SlabNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/http/

Supported methods:
GET-返回 HTTP 相关端点的列表

返回一级 HTTP 端点的列表。

Possible responses:

200 -成功，返回字符串数组
- 404 -未知版本(UnknownVersion)，返回Error

/http/requests

Supported methods:
GET-返回 HTTP 请求统计信息

返回客户端 HTTP 请求的状态。

Request parameters:

fields(string，可选)
- 限制将输出客户端 HTTP 请求统计信息的哪些字段。

Possible responses:

200 -成功，返回HTTP Requests
- 404 -未知版本(UnknownVersion)，返回Error
DELETE-重置 HTTP 请求统计信息

重置客户端 HTTP 请求总数。

Possible responses:

204 -成功
- 404 -未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/http/server_zones/

Supported methods:
GET-所有 HTTP 服务器区域的返回状态

返回每个 HTTP server zone的状态信息。

Request parameters:

fields(string，可选)
- 限制将输出服务器区域的哪些字段。如果“ fields”值为空，则仅输出服务器区域名称。

Possible responses:

200 -成功，为所有 HTTP 服务器区域返回“ HTTP 服务器区域”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/http/server_zones/

所有方法共有的参数：
httpServerZoneName(string，为必填项)
- HTTP 服务器区域的名称。

Supported methods:

GET-HTTP 服务器区域的返回状态

返回特定 HTTP 服务器区域的状态。

Request parameters:

fields(string，可选)
- 限制将输出服务器区域的哪些字段。

Possible responses:

200 -成功，返回HTTP 服务器区域
- 404 -找不到服务器区域(ServerZoneNotFound)，未知版本(UnknownVersion)，返回Error
DELETE-重置 HTTP 服务器区域的统计信息

重置特定 HTTP 服务器区域中接受和丢弃的请求，响应，已接收和已发送字节的统计信息。

Possible responses:

204 -成功
- 404 -找不到服务器区域(ServerZoneNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/http/location_zones/

Supported methods:
GET-所有 HTTP 位置区域的返回状态

返回每个 HTTP location zone的状态信息。

Request parameters:

fields(string，可选)
- 限制将输出位置区域的哪些字段。如果“ fields”值为空，则仅输出区域名称。

Possible responses:

200 -成功，为所有 HTTP 位置区域返回“ HTTP 位置区域”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/http/location_zones/

所有方法共有的参数：
httpLocationZoneName(string，为必填项)
- HTTP location zone的名称。

Supported methods:

GET-HTTP 位置区域的返回状态

返回特定 HTTP location zone的状态。

Request parameters:

fields(string，可选)
- 限制将输出位置区域的哪些字段。

Possible responses:

200 -成功，返回HTTP 位置区域
- 404 -找不到位置区域(LocationZoneNotFound)，未知版本(UnknownVersion)，返回Error
DELETE-重置位置区域的统计信息。

重置特定位置区域中接受和丢弃的请求，响应，已接收和已发送字节的统计信息。

Possible responses:

204 -成功
- 404 -找不到位置区域(LocationZoneNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/http/caches/

Supported methods:
GET-所有缓存的返回状态

返回由proxy_cache_path和其他“ *_cache_path”指令配置的每个缓存的状态。

Request parameters:

fields(string，可选)
- 限制将输出高速缓存区域的哪些字段。如果“ fields”值为空，则仅输出缓存区域的名称。

Possible responses:

200 -成功，为所有 HTTP 缓存返回“ HTTP Cache”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/http/caches/

所有方法共有的参数：
httpCacheZoneName(string，为必填项)
- 缓存区域的名称。

Supported methods:

GET-缓存的返回状态

返回特定缓存的状态。

Request parameters:

fields(string，可选)
- 限制将输出缓存区域的哪些字段。

Possible responses:

200 -成功，返回HTTP Cache
- 404 -未找到缓存(CacheNotFound)，未知版本(UnknownVersion)，返回Error
DELETE-重置缓存统计信息

重置特定缓存区域中缓存命中/未命中的统计信息。

Possible responses:

204 -成功
- 404 -未找到缓存(CacheNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/http/limit_conns/

Supported methods:
GET-所有 HTTP limit_conn 区域的返回状态

返回每个 HTTP limit_conn zone的状态信息。

Request parameters:

fields(string，可选)
- 限制将输出 limit_conn 区域的哪些字段。如果“ fields”值为空，则仅输出区域名称。

Possible responses:

200 -成功，为所有 HTTP 限制连接返回“ HTTP 连接限制”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/http/limit_conns/

所有方法共有的参数：
httpLimitConnZoneName(string，为必填项)
- limit_conn zone的名称。

Supported methods:

GET-HTTP limit_conn 区域的返回状态

返回特定 HTTP limit_conn zone的状态。

Request parameters:

fields(string，可选)
- 限制将输出limit_conn zone的哪些字段。

Possible responses:

200 -成功，返回HTTP 连接限制
- 404 -找不到 limit_conn(LimitConnNotFound)，未知版本(UnknownVersion)，返回Error
DELETE-重置 HTTP limit_conn 区域的统计信息

重置连接限制统计信息。

Possible responses:

204 -成功
- 404 -未找到 limit_conn(LimitConnNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/http/limit_reqs/

Supported methods:
GET-所有 HTTP limit_req 区域的返回状态

返回每个 HTTP limit_req zone的状态信息。

Request parameters:

fields(string，可选)
- 限制将输出 limit_req 区域的哪些字段。如果“ fields”值为空，则仅输出区域名称。

Possible responses:

200 -成功，为所有 HTTP 限制要求返回“ HTTP 请求速率限制”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/http/limit_reqs/

所有方法共有的参数：
httpLimitReqZoneName(string，为必填项)
- limit_req zone的名称。

Supported methods:

GET-HTTP limit_req 区域的返回状态

返回特定 HTTP limit_req zone的状态。

Request parameters:

fields(string，可选)
- 限制将输出limit_req zone的哪些字段。

Possible responses:

200 -成功，返回HTTP 请求速率限制
- 404 -找不到 limit_req(LimitReqNotFound)，未知版本(UnknownVersion)，返回Error
DELETE-重置 HTTP limit_req 区域的统计信息

重置请求限制统计信息。

Possible responses:

204 -成功
- 404 -未找到 limit_req(LimitReqNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/http/upstreams/

Supported methods:
GET-所有 HTTP 上游服务器组的返回状态

返回每个 HTTP 上游服务器组及其服务器的状态。

Request parameters:

fields(string，可选)
- 限制将输出上游服务器组的哪些字段。如果“ fields”值为空，则仅输出上游名称。

Possible responses:

200 -成功，为所有 HTTP 上游返回“ HTTP Upstream”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/http/upstreams//

所有方法共有的参数：
httpUpstreamName(string，为必填项)
- HTTP 上游服务器组的名称。

Supported methods:

GET-HTTP 上游服务器组的返回状态

返回特定的 HTTP 上游服务器组及其服务器的状态。

Request parameters:

fields(string，可选)
- 限制将输出上游服务器组的哪些字段。

Possible responses:

200 -成功，返回HTTP Upstream
- 400 -上游是静态(UpstreamStatic)，返回Error
- 404 -未知版本(UnknownVersion)，未找到上游(UpstreamNotFound)，返回Error
DELETE-重置 HTTP 上游服务器组的统计信息

重置上游服务器组中每个上游服务器的统计信息和队列统计信息。

Possible responses:

204 -成功
- 400 -上游是静态(UpstreamStatic)，返回Error
- 404 -未知版本(UnknownVersion)，找不到上游(UpstreamNotFound)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/http/upstreams//servers/

所有方法共有的参数：
httpUpstreamName(string，为必填项)
- 上游服务器组的名称。

Supported methods:

GET-返回 HTTP 上游服务器组中所有服务器的配置

返回特定 HTTP 上游服务器组中每个服务器的配置。

Possible responses:

200 -成功，返回数组HTTP 上游服务器
- 400 -上游是静态(UpstreamStatic)，返回Error
- 404 -未知版本(UnknownVersion)，未找到上游(UpstreamNotFound)，返回Error
POST-将服务器添加到 HTTP 上游服务器组

将新服务器添加到 HTTP 上游服务器组。服务器参数以 JSON 格式指定。

Request parameters:

postHttpUpstreamServer(HTTP 上游服务器，为必填项)
- 新服务器的地址以及其他 JSON 格式的可选参数。参数“ ID”，“ backup”和“ service”不能更改。

Possible responses:

201 -创建后返回HTTP 上游服务器
- 400 -上游是静态的(UpstreamStatic)，无效的“ parameter”值(UpstreamConfFormatError)，缺少“ server”参数(UpstreamConfFormatError)，未知参数“ name”(UpstreamConfFormatError)，嵌套对象或列表(UpstreamConfFormatError)，解析时为error UpstreamBadAddress)，服务上游“ host”可能没有端口(UpstreamBadAddress)，服务上游“ host”要求域名(UpstreamBadAddress)，无效“ weight”(UpstreamBadWeight)，无效“ max_conns”(UpstreamBadMaxConns)，无效“ max_fails”(UpstreamBadMaxFails)，无效的“ fail_timeout”(UpstreamBadFailTimeout)，无效的“ slow_start”(UpstreamBadSlowStart)，读取请求正文失败BodyReadError)，路由太长(UpstreamBadRoute)，“ service”为空(UpstreamBadService)，未定义要解析的解析器(UpstreamConfNoResolver) ，上游“ name”没有备份(UpstreamNoBackup)，上游“ name”内存用尽(UpstreamOutOfMemory)，返回Error
- 404 -未知版本(UnknownVersion)，找不到上游(UpstreamNotFound)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error
- 409 -条目存在(EntryExists)，返回Error
- 415 -JSON 错误(JsonError)，返回Error

/http/upstreams//servers/

所有方法共有的参数：
httpUpstreamName(string，为必填项)
- 上游服务器组的名称。
- httpUpstreamServerId(string，为必填项)
  - 服务器的 ID。

Supported methods:

GET-返回 HTTP 上游服务器组中服务器的配置

返回 HTTP 上游服务器组中特定服务器的配置。

Possible responses:

200 -成功，返回HTTP 上游服务器
- 400 -上游是静态(UpstreamStatic)，无效的服务器 ID(UpstreamBadServerId)，返回Error
- 404 -ID 为“ id”的服务器不存在(UpstreamServerNotFound)，未知版本(UnknownVersion)，找不到上游(UpstreamNotFound)，返回Error
PATCH-修改 HTTP 上游服务器组中的服务器

修改 HTTP 上游服务器组中特定服务器的设置。服务器参数以 JSON 格式指定。

Request parameters:

patchHttpUpstreamServer(HTTP 上游服务器，为必填项)
- 服务器参数，以 JSON 格式指定。参数“ ID”，“ backup”和“ service”不能更改。

Possible responses:

200 -成功，返回HTTP 上游服务器
- 400 -上游是静态(UpstreamStatic)，无效的“ parameter”值(UpstreamConfFormatError)，未知参数“ name”(UpstreamConfFormatError)，嵌套对象或列表(UpstreamConfFormatError)，解析时(UpstreamBadAddress)是error，参数“ server”无效(UpstreamBadAddress)，无效的服务器 ID(UpstreamBadServerId)，无效的“ weight”(UpstreamBadWeight)，无效的“ max_conns”(UpstreamBadMaxConns)，无效的“ max_fails”(UpstreamBadMaxFails)，无效的_ fail_timeout“(UpstreamBadFailTimeout)，无效的” slow_start“(UpstreamBadSlowStart)，读取请求正文失败BodyReadError)，路由太长(UpstreamBadRoute)，“ service”为空(UpstreamBadService)，服务器“ ID”的地址是不可变的(UpstreamServerImmutable)，服务器“ ID”的权重是不变的(UpstreamServerWeightImmutable)，上游是“ name”内存用完(UpstreamOutOfMemory)，返回Error
- 404 -ID 为“ id”的服务器不存在(UpstreamServerNotFound)，未知版本(UnknownVersion)，找不到上游(UpstreamNotFound)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error
- 415 -JSON 错误(JsonError)，返回Error
DELETE-从 HTTP 上游服务器组中删除服务器

从 HTTP 上游服务器组中删除服务器。

Possible responses:

200 -成功，返回数组HTTP 上游服务器
- 400 -上游是静态(UpstreamStatic)，无效的服务器 ID(UpstreamBadServerId)，服务器“ id”不可移动(UpstreamServerImmutable)，返回Error
- 404 -ID 为“ id”的服务器不存在(UpstreamServerNotFound)，未知版本(UnknownVersion)，找不到上游(UpstreamNotFound)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/http/keyvals/

Supported methods:
GET-从所有 HTTP keyval 区域返回键/值对

返回每个 HTTP 键值共享内存zone的键值对。

Request parameters:

fields(string，可选)
- 如果“ fields”值为空，则仅输出 HTTP keyval 区域名称。

Possible responses:

200 -成功，为所有 HTTP 键值返回“ HTTP 密钥共享存储区”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/http/keyvals/

所有方法共有的参数：
httpKeyvalZoneName(string，为必填项)
- HTTP keyval 共享内存区域的名称。

Supported methods:

GET-从 HTTP keyval 区域返回键/值对

返回存储在特定 HTTP keyval 共享内存zone中的键/值对。

Request parameters:

key(string，可选)
- 从 HTTP keyval 区域获取特定的键值对。

Possible responses:

200 -成功，返回HTTP 密钥共享存储区
- 404 -未找到键值(KeyvalNotFound)，未找到键值键(KeyvalKeyNotFound)，未知版本(UnknownVersion)，返回Error
POST-将键值对添加到 HTTP keyval 区域

将新的键值对添加到 HTTP keyval 共享内存zone。如果 HTTP keyval 共享内存区域为空，则可以输入几个键值对。

Request parameters:

Key-value(HTTP 密钥共享存储区，为必填项)
- 键值对以 JSON 格式指定。如果 HTTP keyval 共享内存区域为空，则可以输入几个键值对。可以使用expire参数(覆盖keyval_zone伪指令的timeout参数)为键值对指定过期时间(以毫秒为单位)。

Possible responses:

201 -已创建
- 400 -无效的 JSON(KeyvalFormatError)，无效的密钥格式(KeyvalFormatError)，所需的密钥(KeyvalFormatError)，未启用密钥超时(KeyvalFormatError)，只能添加一个密钥(KeyvalFormatError)，读取请求正文失败BodyReadError，返回Error
- 404 -找不到密钥(KeyvalNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error
- 409 -条目存在(EntryExists)，键已经存在(KeyvalKeyExists)，返回Error
- 413 -请求实体太大，返回Error
- 415 -JSON 错误(JsonError)，返回Error
PATCH-修改键值或删除键

更改键值对中所选键的值，通过将键值设置为null来删除键，更改键值对的到期时间。如果启用了群集中的关键密钥区域的synchronization，则仅删除目标群集节点上的密钥。可以使用expire参数(覆盖keyval_zone指令的timeout参数)为键值对指定过期时间(以毫秒为单位)。

Request parameters:

httpKeyvalZoneKeyValue(HTTP 密钥共享存储区，为必填项)
- 密钥的新值以 JSON 格式指定。

Possible responses:

204 -成功
- 400 -无效的 JSON(KeyvalFormatError)，需要密钥(KeyvalFormatError)，未启用密钥 val 超时(KeyvalFormatError)，只能更新一个密钥(KeyvalFormatError)，读取请求正文失败BodyReadError)，返回Error
- 404 -未找到键值(KeyvalNotFound)，未找到键值键(KeyvalKeyNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error
- 413 -请求实体太大，返回Error
- 415 -JSON 错误(JsonError)，返回Error
DELETE-清空 HTTP keyval 区域

从 HTTP keyval 共享内存zone删除所有键值对。如果启用了群集中synchronization的关键密钥区，则仅清空目标集群节点上的关键密钥区。

Possible responses:

204 -成功
- 404 -找不到密钥(KeyvalNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/stream/

Supported methods:
GET-返回与流相关的端点的列表

返回一级流端点的列表。

Possible responses:

200 -成功，返回字符串数组
- 404 -未知版本(UnknownVersion)，返回Error

/stream/server_zones/

Supported methods:
GET-所有流服务器区域的返回状态

返回每个流server zone的状态信息。

Request parameters:

fields(string，可选)
- 限制将输出服务器区域的哪些字段。如果“ fields”值为空，则仅输出服务器区域名称。

Possible responses:

200 -成功，为所有流服务器区域返回“ 流服务器区域”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/stream/server_zones/

所有方法共有的参数：
streamServerZoneName(string，为必填项)
- 流服务器区域的名称。

Supported methods:

GET-流服务器区域的返回状态

返回特定流服务器区域的状态。

Request parameters:

fields(string，可选)
- 限制将输出服务器区域的哪些字段。

Possible responses:

200 -成功，返回流服务器区域
- 404 -找不到服务器区域(ServerZoneNotFound)，未知版本(UnknownVersion)，返回Error
DELETE-重置流服务器区域的统计信息

重置特定流服务器区域中接受和丢弃的连接，会话，已接收和已发送字节的统计信息。

Possible responses:

204 -成功
- 404 -找不到服务器区域(ServerZoneNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/stream/limit_conns/

Supported methods:
GET-所有流 limit_conn 区域的返回状态

返回每个流limit_conn zone的状态信息。

Request parameters:

fields(string，可选)
- 限制将输出 limit_conn 区域的哪些字段。如果“ fields”值为空，则仅输出区域名称。

Possible responses:

200 -成功，为所有流限制 conns 返回“ 流连接限制”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/stream/limit_conns/

所有方法共有的参数：
streamLimitConnZoneName(string，为必填项)
- limit_conn zone的名称。

Supported methods:

GET-流 limit_conn 区域的返回状态

返回特定流limit_conn zone的状态。

Request parameters:

fields(string，可选)
- 限制将输出limit_conn zone的哪些字段。

Possible responses:

200 -成功，返回流连接限制
- 404 -找不到 limit_conn(LimitConnNotFound)，未知版本(UnknownVersion)，返回Error
DELETE-重置流 limit_conn 区域的统计信息

重置连接限制统计信息。

Possible responses:

204 -成功
- 404 -未找到 limit_conn(LimitConnNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/stream/upstreams/

Supported methods:
GET-所有流上游服务器组的返回状态

返回每个流上游服务器组及其服务器的状态。

Request parameters:

fields(string，可选)
- 限制将输出上游服务器组的哪些字段。如果“ fields”值为空，则仅输出上游名称。

Possible responses:

200 -成功，为所有流上游返回“ Stream Upstream”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/stream/upstreams//

所有方法共有的参数：
streamUpstreamName(string，为必填项)
- 流上游服务器组的名称。

Supported methods:

GET-流上游服务器组的返回状态

返回特定流上游服务器组及其服务器的状态。

Request parameters:

fields(string，可选)
- 限制将输出上游服务器组的哪些字段。

Possible responses:

200 -成功，返回Stream Upstream
- 400 -上游是静态(UpstreamStatic)，返回Error
- 404 -未知版本(UnknownVersion)，未找到上游(UpstreamNotFound)，返回Error
DELETE-重置流上游服务器组的统计信息

重置上游服务器组中每个上游服务器的统计信息。

Possible responses:

204 -成功
- 400 -上游是静态(UpstreamStatic)，返回Error
- 404 -未知版本(UnknownVersion)，找不到上游(UpstreamNotFound)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/stream/upstreams//servers/

所有方法共有的参数：
streamUpstreamName(string，为必填项)
- 上游服务器组的名称。

Supported methods:

GET-返回流上游服务器组中所有服务器的配置

返回特定流上游服务器组中每个服务器的配置。

Possible responses:

200 -成功，返回数组流上游服务器
- 400 -上游是静态(UpstreamStatic)，返回Error
- 404 -未知版本(UnknownVersion)，未找到上游(UpstreamNotFound)，返回Error
POST-将服务器添加到流上游服务器组

将新服务器添加到流上游服务器组。服务器参数以 JSON 格式指定。

Request parameters:

postStreamUpstreamServer(流上游服务器，为必填项)
- 新服务器的地址以及其他 JSON 格式的可选参数。参数“ ID”，“ backup”和“ service”不能更改。

Possible responses:

201 -创建后返回流上游服务器
- 400 -上游是静态(UpstreamStatic)，无效的“ parameter”值(UpstreamConfFormatError)，缺少“ server”参数(UpstreamConfFormatError)，未知参数“ name”(UpstreamConfFormatError)，嵌套对象或列表(UpstreamConfFormatError)，解析时为error UpstreamBadAddress)，服务器“ host”(UpstreamBadAddress)中没有端口，上游服务“ host”可能没有端口(UpstreamBadAddress)，上游服务“ host”需要域名(UpstreamBadAddress)，无效的“ weight”(UpstreamBadWeight)，无效的max_conns “(UpstreamBadMaxConns)，无效” max_fails“(UpstreamBadMaxFails)，无效” fail_timeout“(UpstreamBadFailTimeout)，无效” slow_start“(UpstreamBadSlowStart)，” service“为空(UpstreamBadService)，未定义解析器来解析(UpstreamConfNoResolver)，上游是” name没有备份(UpstreamNoBackup)，上游“ name”内存已用尽(UpstreamOutOfMemory)，读取请求正文失败BodyReadError)，返回Error
- 404 -未知版本(UnknownVersion)，找不到上游(UpstreamNotFound)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error
- 409 -条目存在(EntryExists)，返回Error
- 415 -JSON 错误(JsonError)，返回Error

/stream/upstreams//servers/

所有方法共有的参数：
streamUpstreamName(string，为必填项)
- 上游服务器组的名称。
- streamUpstreamServerId(string，为必填项)
  - 服务器的 ID。

Supported methods:

GET-返回流上游服务器组中服务器的配置

返回流上游服务器组中特定服务器的配置。

Possible responses:

200 -成功，返回流上游服务器
- 400 -上游是静态(UpstreamStatic)，无效的服务器 ID(UpstreamBadServerId)，返回Error
- 404 -未知版本(UnknownVersion)，上游未找到(UpstreamNotFound)，ID 为_ id的服务器不存在(UpstreamServerNotFound)，返回Error
PATCH-修改流上游服务器组中的服务器

修改流上游服务器组中特定服务器的设置。服务器参数以 JSON 格式指定。

Request parameters:

patchStreamUpstreamServer(流上游服务器，为必填项)
- 服务器参数，以 JSON 格式指定。参数“ ID”，“ backup”和“ service”不能更改。

Possible responses:

200 -成功，返回流上游服务器
- 400 -上游是静态(UpstreamStatic)，无效的“ parameter”值(UpstreamConfFormatError)，未知参数“ name”(UpstreamConfFormatError)，嵌套对象或列表(UpstreamConfFormatError)，解析时(UpstreamBadAddress)的“ error”，参数“ server”无效(UpstreamBadAddress)，服务器“ host”(UpstreamBadAddress)中没有端口，无效的服务器 ID(UpstreamBadServerId)，无效的“ weight”(UpstreamBadWeight)，无效的“ max_conns”(UpstreamBadMaxConns)，无效的“ max_fails”(UpstreamBadMaxFails)，无效的“ fail_timeout”(UpstreamBadFailTimeout)，无效的“ slow_start”(UpstreamBadSlowStart)，读取请求正文失败BodyReadError)，“ service”为空(UpstreamBadService)，服务器“ ID”的地址是不可变的(UpstreamServerImmutable)，服务器“ ID”的权重是不可变的(UpstreamServerWeightImmutable)，上游“ name”内存用尽(UpstreamOutOfMemory)，返回Error
- 404 -ID 为“ id”的服务器不存在(UpstreamServerNotFound)，未知版本(UnknownVersion)，找不到上游(UpstreamNotFound)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error
- 415 -JSON 错误(JsonError)，返回Error
DELETE-从流上游服务器组中删除服务器

从流服务器组中删除服务器。

Possible responses:

200 -成功，返回数组流上游服务器
- 400 -上游是静态(UpstreamStatic)，无效的服务器 ID(UpstreamBadServerId)，服务器“ id”不可移动(UpstreamServerImmutable)，返回Error
- 404 -ID 为“ id”的服务器不存在(UpstreamServerNotFound)，未知版本(UnknownVersion)，找不到上游(UpstreamNotFound)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/stream/keyvals/

Supported methods:
GET-从所有流 keyval 区域返回键值对

返回每个流 keyval 共享内存zone的键/值对。

Request parameters:

fields(string，可选)
- 如果“ fields”值为空，则仅输出流密钥区名称。

Possible responses:

200 -成功，为所有流键值返回“ 流密钥共享存储区”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/stream/keyvals/

所有方法共有的参数：
streamKeyvalZoneName(string，为必填项)
- 流 keyval 共享内存区域的名称。

Supported methods:

GET-从流 keyval 区域返回键/值对

返回存储在特定流 keyval 共享内存zone中的键值对。

Request parameters:

key(string，可选)
- 从流 keyval 区域获取特定的键值对。

Possible responses:

200 -成功，返回流密钥共享存储区
- 404 -未找到键值(KeyvalNotFound)，未找到键值键(KeyvalKeyNotFound)，未知版本(UnknownVersion)，返回Error
POST-将键值对添加到流 keyval 区域

将新的键/值对添加到流 keyval 共享内存zone。如果流 keyval 共享存储区为空，则可以输入几个键值对。

Request parameters:

Key-value(流密钥共享存储区，为必填项)
- 键值对以 JSON 格式指定。如果流 keyval 共享存储区为空，则可以输入几个键值对。可以使用expire参数(覆盖keyval_zone伪指令的timeout参数)为键值对指定过期时间(以毫秒为单位)。

Possible responses:

201 -已创建
- 400 -无效的 JSON(KeyvalFormatError)，无效的密钥格式(KeyvalFormatError)，所需的密钥(KeyvalFormatError)，未启用密钥超时(KeyvalFormatError)，只能添加一个密钥(KeyvalFormatError)，读取请求正文失败BodyReadError，返回Error
- 404 -找不到密钥(KeyvalNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error
- 409 -条目存在(EntryExists)，键已经存在(KeyvalKeyExists)，返回Error
- 413 -请求实体太大，返回Error
- 415 -JSON 错误(JsonError)，返回Error
PATCH-修改键值或删除键

更改键值对中所选键的值，通过将键值设置为null来删除键，更改键值对的到期时间。如果启用了群集中的关键密钥区域的synchronization，则仅删除目标群集节点上的密钥。使用expire参数指定有效时间(以毫秒为单位)，该参数将覆盖keyval_zone指令的timeout参数。

Request parameters:

streamKeyvalZoneKeyValue(流密钥共享存储区，为必填项)
- 密钥的新值以 JSON 格式指定。

Possible responses:

204 -成功
- 400 -无效的 JSON(KeyvalFormatError)，需要密钥(KeyvalFormatError)，未启用密钥 val 超时(KeyvalFormatError)，只能更新一个密钥(KeyvalFormatError)，读取请求正文失败BodyReadError)，返回Error
- 404 -未找到键值(KeyvalNotFound)，未找到键值键(KeyvalKeyNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error
- 413 -请求实体太大，返回Error
- 415 -JSON 错误(JsonError)，返回Error
DELETE-清空流密钥区

从流 keyval 共享内存zone中删除所有键值对。如果启用了群集中synchronization的关键密钥区，则仅清空目标集群节点上的关键密钥区。

Possible responses:

204 -成功
- 404 -找不到密钥(KeyvalNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/stream/zone_sync/

Supported methods:
GET-返回节点的同步状态

返回集群节点的同步状态。

Possible responses:

200 -成功，返回流区同步节点
- 404 -未知版本(UnknownVersion)，返回Error

/resolvers/

Supported methods:
GET-所有解析器区域的返回状态

返回每个resolver zone的状态信息。

Request parameters:

fields(string，可选)
- 限制输出解析器统计信息的字段。

Possible responses:

200 -成功，为所有解析器返回“ Resolver Zone”对象的集合
- 404 -未知版本(UnknownVersion)，返回Error

/resolvers/

所有方法共有的参数：
resolverZoneName(string，为必填项)
- 解析器区域的名称。

Supported methods:

GET-返回解析器区域的统计信息

返回存储在特定解析器zone中的统计信息。

Request parameters:

fields(string，可选)
- 限制将输出解析器区域的哪些字段(请求，响应或两者)。

Possible responses:

200 -成功，返回Resolver Zone
- 404 -找不到解析器区域(ResolverZoneNotFound)，未知版本(UnknownVersion)，返回Error
DELETE-重置解析器区域的统计信息。

重置特定解析器区域中的统计信息。

Possible responses:

204 -成功
- 404 -找不到解析器区域(ResolverZoneNotFound)，未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

/ssl

Supported methods:
GET-返回 SSL 统计信息

返回 SSL 统计信息。

Request parameters:

fields(string，可选)
- 限制将输出 SSL 统计信息的哪些字段。

Possible responses:

200 -成功，返回SSL
- 404 -未知版本(UnknownVersion)，返回Error
DELETE-重置 SSL 统计信息

重置 SSL 握手和会话重用的计数器。

Possible responses:

204 -成功
- 404 -未知版本(UnknownVersion)，返回Error
- 405 -方法已禁用(MethodDisabled)，返回Error

Response Objects

nginx:

有关 Nginx 的一般信息：

version ( string )
- Nginx 的版本。
build ( string )
- Nginx 构建的名称。
address ( string )
- 接受状态请求的服务器的地址。
generation ( integer )
- 配置总数reloads。
load_timestamp ( string )
- 上次重新加载配置的时间，采用 ISO 8601 格式，分辨率为毫秒。
timestamp ( string )
- ISO 8601 格式的当前时间，以毫秒为单位。
pid ( integer )
- 处理状态请求的工作进程的 ID。
ppid ( integer )
- 启动worker process的主进程的 ID。

Example:

{
  "nginx" : {
    "version" : "1.17.3",
    "build" : "nginx-plus-r19",
    "address" : "206.251.255.64",
    "generation" : 6,
    "load_timestamp" : "2019-10-01T11:15:44.467Z",
    "timestamp" : "2019-10-01T09:26:07.305Z",
    "pid" : 32212,
    "ppid" : 32210
  }
}

Processes:
respawned ( integer )
- 异常终止和重生的子进程的总数。

Example:

{
  "respawned" : 0
}

Connections:

接受，断开，活动和空闲连接的数量。

accepted ( integer )
- 接受的客户端连接总数。
dropped ( integer )
- 断开的客户端连接总数。
active ( integer )
- 当前活动的客户端连接数。
idle ( integer )
- 当前空闲的客户端连接数。

Example:

{
  "accepted" : 4968119,
  "dropped" : 0,
  "active" : 5,
  "idle" : 117
}

SSL:
handshakes ( integer )
- 成功的 SSL 握手总数。
handshakes_failed ( integer )
- SSL 握手失败的总数。
session_reuses ( integer )
- SSL 握手期间会话重用的总数。

Example:

{
  "handshakes" : 79572,
  "handshakes_failed" : 21025,
  "session_reuses" : 15762
}

与平板分配器共享的内存区域：
pages
- 可用和已用内存页数。
used ( integer )
- 当前已使用的内存页数。
- free ( integer )
  - 当前的可用内存页数。
slots
- 内存插槽的状态数据(8、16、32、64、128 等)

“ Memory Slot”对象的集合

Example:

{
  "pages" : {
    "used" : 1143,
    "free" : 2928
  },
  "slots" : {
    "8" : {
      "used" : 0,
      "free" : 0,
      "reqs" : 0,
      "fails" : 0
    },
    "16" : {
      "used" : 0,
      "free" : 0,
      "reqs" : 0,
      "fails" : 0
    },
    "32" : {
      "used" : 0,
      "free" : 0,
      "reqs" : 0,
      "fails" : 0
    },
    "64" : {
      "used" : 1,
      "free" : 63,
      "reqs" : 1,
      "fails" : 0
    },
    "128" : {
      "used" : 0,
      "free" : 0,
      "reqs" : 0,
      "fails" : 0
    },
    "256" : {
      "used" : 18078,
      "free" : 178,
      "reqs" : 1635736,
      "fails" : 0
    }
  }
}

Memory Slot:
used ( integer )
- 当前已用内存插槽的数量。
free ( integer )
- 当前的可用内存插槽数。
reqs ( integer )
- 分配指定大小的内存的总尝试次数。
fails ( integer )
- 尝试分配指定大小的内存失败的次数。
HTTP Requests:
total ( integer )
- 客户端请求总数。
current ( integer )
- 当前的客户端请求数。

Example:

{
  "total" : 10624511,
  "current" : 4
}

HTTP 服务器区域：
processing ( integer )
- 当前正在处理的客户端请求数。
requests ( integer )
- 从客户端收到的客户端请求总数。
responses
- 发送给客户端的响应总数，以及状态码为“ 1xx”，“ 2xx”，“ 3xx”，“ 4xx”和“ 5xx”的响应的数量。
1xx ( integer )
- 状态代码为“ 1xx”的响应数。
- 2xx ( integer )
  - 状态代码为“ 2xx”的响应数。
- 3xx ( integer )
  - 状态代码为“ 3xx”的响应数。
- 4xx ( integer )
  - 状态代码为“ 4xx”的响应数。
- 5xx ( integer )
  - 状态代码为“ 5xx”的响应数。
- total ( integer )
  - 发送给客户的响应总数。
discarded ( integer )
- 没有发送响应的已完成请求总数。
received ( integer )
- 从客户端收到的字节总数。
sent ( integer )
- 发送给客户端的字节总数。

Example:

{
  "processing" : 1,
  "requests" : 706690,
  "responses" : {
    "1xx" : 0,
    "2xx" : 699482,
    "3xx" : 4522,
    "4xx" : 907,
    "5xx" : 266,
    "total" : 705177
  },
  "discarded" : 1513,
  "received" : 172711587,
  "sent" : 19415530115
}

HTTP 位置区域：
requests ( integer )
- 从客户端收到的客户端请求总数。
responses
- 发送给客户端的响应总数，以及状态码为“ 1xx”，“ 2xx”，“ 3xx”，“ 4xx”和“ 5xx”的响应的数量。
1xx ( integer )
- 状态代码为“ 1xx”的响应数。
- 2xx ( integer )
  - 状态代码为“ 2xx”的响应数。
- 3xx ( integer )
  - 状态代码为“ 3xx”的响应数。
- 4xx ( integer )
  - 状态代码为“ 4xx”的响应数。
- 5xx ( integer )
  - 状态代码为“ 5xx”的响应数。
- total ( integer )
  - 发送给客户的响应总数。
discarded ( integer )
- 没有发送响应的已完成请求总数。
received ( integer )
- 从客户端收到的字节总数。
sent ( integer )
- 发送给客户端的字节总数。

Example:

{
  "requests" : 706690,
  "responses" : {
    "1xx" : 0,
    "2xx" : 699482,
    "3xx" : 4522,
    "4xx" : 907,
    "5xx" : 266,
    "total" : 705177
  },
  "discarded" : 1513,
  "received" : 172711587,
  "sent" : 19415530115
}

HTTP Cache:
size ( integer )
- 当前缓存的大小。
max_size ( integer )
- 配置中指定的最大缓存大小限制。
cold ( boolean )
- 一个布尔值，指示“缓存加载器”进程是否仍在将数据从磁盘加载到缓存中。
hit
- - responses ( integer )
  - 从缓存中读取的valid个响应总数。
- bytes ( integer )
  - 从缓存读取的字节总数。
stale
- - responses ( integer )
  - 从缓存中读取的过期响应总数(请参见proxy_cache_use_stale和其他“ *_cache_use_stale”指令)。
- bytes ( integer )
  - 从缓存读取的字节总数。
updating
- - responses ( integer )
  - 在更新响应时从缓存读取的过期响应总数(请参见proxy_cache_use_stale和其他“ *_cache_use_stale”指令)。
- bytes ( integer )
  - 从缓存读取的字节总数。
revalidated
- - responses ( integer )
  - 从缓存读取的过期和重新验证的响应总数(请参阅proxy_cache_revalidate和其他“ *_cache_revalidate”指令)。
- bytes ( integer )
  - 从缓存读取的字节总数。
miss
- - responses ( integer )
  - 在缓存中找不到的响应总数。
- bytes ( integer )
  - 从代理服务器读取的字节总数。
- responses_written ( integer )
  - 写入缓存的响应总数。
- bytes_written ( integer )
  - 写入缓存的总字节数。
expired
- - responses ( integer )
  - 未从缓存中获取的过期响应总数。
- bytes ( integer )
  - 从代理服务器读取的字节总数。
- responses_written ( integer )
  - 写入缓存的响应总数。
- bytes_written ( integer )
  - 写入缓存的总字节数。
bypass
- - responses ( integer )
  - 由于proxy_cache_bypass和其他“ *_cache_bypass”指令，未在缓存中查找的响应总数。
- bytes ( integer )
  - 从代理服务器读取的字节总数。
- responses_written ( integer )
  - 写入缓存的响应总数。
- bytes_written ( integer )
  - 写入缓存的总字节数。

Example:

{
  "size" : 530915328,
  "max_size" : 536870912,
  "cold" : false,
  "hit" : {
    "responses" : 254032,
    "bytes" : 6685627875
  },
  "stale" : {
    "responses" : 0,
    "bytes" : 0
  },
  "updating" : {
    "responses" : 0,
    "bytes" : 0
  },
  "revalidated" : {
    "responses" : 0,
    "bytes" : 0
  },
  "miss" : {
    "responses" : 1619201,
    "bytes" : 53841943822
  },
  "expired" : {
    "responses" : 45859,
    "bytes" : 1656847080,
    "responses_written" : 44992,
    "bytes_written" : 1641825173
  },
  "bypass" : {
    "responses" : 200187,
    "bytes" : 5510647548,
    "responses_written" : 200173,
    "bytes_written" : 44992
  }
}

HTTP 连接限制：
passed ( integer )
- 既没有限制也没有被视为限制的连接总数。
rejected ( integer )
- 拒绝的连接总数。
rejected_dry_run ( integer )
- 在dry run模式下被拒绝的连接总数。

Example:

{
  "passed" : 15,
  "rejected" : 0,
  "rejected_dry_run" : 2
}

HTTP 请求速率限制：
passed ( integer )
- 既不受限也不视为受限的请求总数。
delayed ( integer )
- 延迟的请求总数。
rejected ( integer )
- 被拒绝的请求总数。
delayed_dry_run ( integer )
- 在dry run模式下延迟的请求总数。
rejected_dry_run ( integer )
- 在dry run模式下被拒绝的请求总数。

Example:

{
  "passed" : 15,
  "delayed" : 4,
  "rejected" : 0,
  "delayed_dry_run" : 1,
  "rejected_dry_run" : 2
}

HTTP Upstream:
peers
- 数组：
id ( integer )
- 服务器的 ID。
- server ( string )
  - 服务器的address。
- service ( string )
  - server指令的service参数值。
- name ( string )
  - server指令中指定的服务器名称。
- backup ( boolean )
  - 指示服务器是否为backup服务器的布尔值。
- weight ( integer )
  - 服务器的Weight。
- state ( string )
  - 当前状态，可以是“ up”，“ draining”，“ down”，“ unavail”，“ checking”和“ unhealthy”之一。
- active ( integer )
  - 当前活动连接数。
- max_conns ( integer )
  - 服务器的max_conns限制。
- requests ( integer )
  - 转发到该服务器的客户端请求总数。
- responses
  - - 1xx ( integer )
    - 状态代码为“ 1xx”的响应数。
  - 2xx ( integer )
    - 状态代码为“ 2xx”的响应数。
  - 3xx ( integer )
    - 状态代码为“ 3xx”的响应数。
  - 4xx ( integer )
    - 状态代码为“ 4xx”的响应数。
  - 5xx ( integer )
    - 状态代码为“ 5xx”的响应数。
  - total ( integer )
    - 从该服务器获得的响应总数。
- sent ( integer )
  - 发送到此服务器的字节总数。
- received ( integer )
  - 从该服务器接收的字节总数。
- fails ( integer )
  - 与服务器通信失败的尝试总数。
- unavail ( integer )
  - 由于未成功尝试的次数达到max_fails阈值，服务器对客户端请求(状态“ unavail”)不可用的次数。
- health_checks
  - - checks ( integer )
    - 发出的health check个请求总数。
  - fails ( integer )
    - 运行状况检查失败的次数。
  - unhealthy ( integer )
    - 服务器不正常运行了多少次(状态“ unhealthy”)。
  - last_passed ( boolean )
    - 布尔值，指示上一次运行状况检查请求是否成功并且已通过tests。
- downtime ( integer )
  - 服务器处于“ unavail”，“ checking”和“ unhealthy”状态的总时间。
- downstart ( string )
  - 服务器以 ISO 8601 格式(毫秒分辨率)成为“ unavail”，“ checking”或“ unhealthy”的时间。
- selected ( string )
  - 上次选择服务器处理请求的时间，ISO 8601 格式，毫秒级分辨率。
- header_time ( integer )
  - 从服务器获取response header的平均时间。
- response_time ( integer )
  - 从服务器获取full response的平均时间。
keepalive ( integer )
- 当前空闲的keepalive连接数。
zombies ( integer )
- 当前从组中删除但仍在处理活动客户端请求的服务器数。
zone ( string )
- 保留组的配置和运行时状态的共享内存zone的名称。
queue
- 对于请求queue，提供了以下数据：
size ( integer )
- 队列中的当前请求数。
- max_size ( integer )
  - 可以同时在队列中的最大请求数。
- overflows ( integer )
  - 由于队列溢出而被拒绝的请求总数。

Example:

{
  "upstream_backend" : {
    "peers" : [
      {
        "id" : 0,
        "server" : "10.0.0.1:8088",
        "name" : "10.0.0.1:8088",
        "backup" : false,
        "weight" : 5,
        "state" : "up",
        "active" : 0,
        "max_conns" : 20,
        "requests" : 667231,
        "header_time" : 20,
        "response_time" : 36,
        "responses" : {
          "1xx" : 0,
          "2xx" : 666310,
          "3xx" : 0,
          "4xx" : 915,
          "5xx" : 6,
          "total" : 667231
        },
        "sent" : 251946292,
        "received" : 19222475454,
        "fails" : 0,
        "unavail" : 0,
        "health_checks" : {
          "checks" : 26214,
          "fails" : 0,
          "unhealthy" : 0,
          "last_passed" : true
        },
        "downtime" : 0,
        "downstart" : "2019-10-01T11:09:21.602Z",
        "selected" : "2019-10-01T15:01:25.000Z"
      },
      {
        "id" : 1,
        "server" : "10.0.0.1:8089",
        "name" : "10.0.0.1:8089",
        "backup" : true,
        "weight" : 1,
        "state" : "unhealthy",
        "active" : 0,
        "max_conns" : 20,
        "requests" : 0,
        "responses" : {
          "1xx" : 0,
          "2xx" : 0,
          "3xx" : 0,
          "4xx" : 0,
          "5xx" : 0,
          "total" : 0
        },
        "sent" : 0,
        "received" : 0,
        "fails" : 0,
        "unavail" : 0,
        "health_checks" : {
          "checks" : 26284,
          "fails" : 26284,
          "unhealthy" : 1,
          "last_passed" : false
        },
        "downtime" : 262925617,
        "downstart" : "2019-10-01T11:09:21.602Z",
        "selected" : "2019-10-01T15:01:25.000Z"
      }
    ],
    "keepalive" : 0,
    "zombies" : 0,
    "zone" : "upstream_backend"
  }
}

HTTP 上游服务器：

HTTP 上游server的动态可配置参数：

id ( integer )
- HTTP 上游服务器的 ID。 ID 是自动分配的，无法更改。
server ( string )
- 与 HTTP 上游服务器的address参数相同。添加服务器时，可以将其指定为域名。在这种情况下，将监视与域名对应的 IP 地址的更改，并将其自动应用于上游配置，而无需重新启动 nginx。这需要在“ http”块中使用resolver指令。另请参见 HTTP 上游服务器的resolve参数。
service ( string )
- 与 HTTP 上游服务器的service参数相同。此参数无法更改。
weight ( integer )
- 与 HTTP 上游服务器的weight参数相同。
max_conns ( integer )
- 与 HTTP 上游服务器的max_conns参数相同。
max_fails ( integer )
- 与 HTTP 上游服务器的max_fails参数相同。
fail_timeout ( string )
- 与 HTTP 上游服务器的fail_timeout参数相同。
slow_start ( string )
- 与 HTTP 上游服务器的slow_start参数相同。
route ( string )
- 与 HTTP 上游服务器的route参数相同。
backup ( boolean )
- 当true时，添加一个backup服务器。此参数无法更改。
down ( boolean )
- 与 HTTP 上游服务器的down参数相同。
drain ( boolean )
- 与 HTTP 上游服务器的drain参数相同。
parent ( string )
- 解析服务器的父服务器 ID。 ID 是自动分配的，无法更改。
host ( string )
- 解析服务器的主机名。主机名是自动分配的，不能更改。

Example:

{
  "id" : 1,
  "server" : "10.0.0.1:8089",
  "weight" : 4,
  "max_conns" : 0,
  "max_fails" : 0,
  "fail_timeout" : "10s",
  "slow_start" : "10s",
  "route" : "",
  "backup" : true,
  "down" : true
}

HTTP 密钥共享存储区：

使用 GET 方法时，HTTP keyval 共享内存区域的内容。

Example:

{
  "key1" : "value1",
  "key2" : "value2",
  "key3" : "value3"
}

HTTP 密钥共享存储区：

使用 POST 或 PATCH 方法时，HTTP keyval 共享内存区域的内容。

Example:

{
  "key1" : "value1",
  "key2" : "value2",
  "key3" : {
    "value" : "value3",
    "expire" : 30000
  }
}

流服务器区域：
processing ( integer )
- 当前正在处理的客户端连接数。
connections ( integer )
- 客户端接受的连接总数。
sessions
- 已完成的会话总数，以及以状态代码“ 2xx”，“ 4xx”或“ 5xx”完成的会话数。
2xx ( integer )
- 以status codes“ 2xx”完成的会话总数。
- 4xx ( integer )
  - 以status codes“ 4xx”完成的会话总数。
- 5xx ( integer )
  - 以status codes“ 5xx”完成的会话总数。
- total ( integer )
  - 完成的客户会话总数。
discarded ( integer )
- 不创建会话而完成的连接总数。
received ( integer )
- 从客户端收到的字节总数。
sent ( integer )
- 发送给客户端的字节总数。

Example:

{
  "dns" : {
    "processing" : 1,
    "connections" : 155569,
    "sessions" : {
      "2xx" : 155564,
      "4xx" : 0,
      "5xx" : 0,
      "total" : 155569
    },
    "discarded" : 0,
    "received" : 4200363,
    "sent" : 20489184
  }
}

流连接限制：
passed ( integer )
- 既没有限制也没有被视为限制的连接总数。
rejected ( integer )
- 拒绝的连接总数。
rejected_dry_run ( integer )
- 在dry run模式下被拒绝的连接总数。

Example:

{
  "passed" : 15,
  "rejected" : 0,
  "rejected_dry_run" : 2
}

Stream Upstream:
peers
- 数组：
id ( integer )
- 服务器的 ID。
- server ( string )
  - 服务器的address。
- service ( string )
  - server指令的service参数值。
- name ( string )
  - server指令中指定的服务器名称。
- backup ( boolean )
  - 指示服务器是否为backup服务器的布尔值。
- weight ( integer )
  - 服务器的Weight。
- state ( string )
  - 当前状态，可以是“ up”，“ down”，“ unavail”，“ checking”或“ unhealthy”之一。
- active ( integer )
  - 当前的连接数。
- max_conns ( integer )
  - 服务器的max_conns限制。
- connections ( integer )
  - 转发到该服务器的客户端连接总数。
- connect_time ( integer )
  - 连接到上游服务器的平均时间。
- first_byte_time ( integer )
  - 接收数据第一个字节的平均时间。
- response_time ( integer )
  - 接收数据最后一个字节的平均时间。
- sent ( integer )
  - 发送到此服务器的字节总数。
- received ( integer )
  - 从该服务器接收的字节总数。
- fails ( integer )
  - 与服务器通信失败的尝试总数。
- unavail ( integer )
  - 由于未成功尝试达到max_fails阈值的次数，服务器无法连接客户端连接(状态“ unavail”)的次数。
- health_checks
  - - checks ( integer )
    - 发出的health check个请求总数。
  - fails ( integer )
    - 运行状况检查失败的次数。
  - unhealthy ( integer )
    - 服务器不正常运行了多少次(状态“ unhealthy”)。
  - last_passed ( boolean )
    - 指示上一次运行状况检查请求是否成功并通过tests的布尔值。
- downtime ( integer )
  - 服务器处于“ unavail”，“ checking”和“ unhealthy”状态的总时间。
- downstart ( string )
  - 服务器以 ISO 8601 格式(毫秒分辨率)成为“ unavail”，“ checking”或“ unhealthy”的时间。
- selected ( string )
  - 上次选择服务器处理连接的时间，ISO 8601 格式，毫秒级分辨率。
zombies ( integer )
- 当前从组中删除的服务器数量，但仍在处理活动的客户端连接。
zone ( string )
- 保留组的配置和运行时状态的共享内存zone的名称。

Example:

{
  "dns" : {
    "peers" : [
      {
        "id" : 0,
        "server" : "10.0.0.1:12347",
        "name" : "10.0.0.1:12347",
        "backup" : false,
        "weight" : 5,
        "state" : "up",
        "active" : 0,
        "max_conns" : 50,
        "connections" : 667231,
        "sent" : 251946292,
        "received" : 19222475454,
        "fails" : 0,
        "unavail" : 0,
        "health_checks" : {
          "checks" : 26214,
          "fails" : 0,
          "unhealthy" : 0,
          "last_passed" : true
        },
        "downtime" : 0,
        "downstart" : "2019-10-01T11:09:21.602Z",
        "selected" : "2019-10-01T15:01:25.000Z"
      },
      {
        "id" : 1,
        "server" : "10.0.0.1:12348",
        "name" : "10.0.0.1:12348",
        "backup" : true,
        "weight" : 1,
        "state" : "unhealthy",
        "active" : 0,
        "max_conns" : 50,
        "connections" : 0,
        "sent" : 0,
        "received" : 0,
        "fails" : 0,
        "unavail" : 0,
        "health_checks" : {
          "checks" : 26284,
          "fails" : 26284,
          "unhealthy" : 1,
          "last_passed" : false
        },
        "downtime" : 262925617,
        "downstart" : "2019-10-01T11:09:21.602Z",
        "selected" : "2019-10-01T15:01:25.000Z"
      }
    ],
    "zombies" : 0,
    "zone" : "dns"
  }
}

流上游服务器：

上游server的流的动态可配置参数：

id ( integer )
- 流上游服务器的 ID。 ID 是自动分配的，无法更改。
server ( string )
- 与流上游服务器的address参数相同。添加服务器时，可以将其指定为域名。在这种情况下，将监视与域名对应的 IP 地址的更改，并将其自动应用于上游配置，而无需重新启动 nginx。这需要在“ stream”块中使用resolver指令。另请参见流上游服务器的resolve参数。
service ( string )
- 与流上游服务器的service参数相同。此参数无法更改。
weight ( integer )
- 与流上游服务器的weight参数相同。
max_conns ( integer )
- 与流上游服务器的max_conns参数相同。
max_fails ( integer )
- 与流上游服务器的max_fails参数相同。
fail_timeout ( string )
- 与流上游服务器的fail_timeout参数相同。
slow_start ( string )
- 与流上游服务器的slow_start参数相同。
backup ( boolean )
- 当true时，添加一个backup服务器。此参数无法更改。
down ( boolean )
- 与流上游服务器的down参数相同。
parent ( string )
- 解析服务器的父服务器 ID。 ID 是自动分配的，无法更改。
host ( string )
- 解析服务器的主机名。主机名是自动分配的，不能更改。

Example:

{
  "id" : 0,
  "server" : "10.0.0.1:12348",
  "weight" : 1,
  "max_conns" : 0,
  "max_fails" : 1,
  "fail_timeout" : "10s",
  "slow_start" : 0,
  "backup" : false,
  "down" : false
}

流密钥共享存储区：

使用 GET 方法时，流 keyval 共享内存区域的内容。

Example:

{
  "key1" : "value1",
  "key2" : "value2",
  "key3" : "value3"
}

流密钥共享存储区：

使用 POST 或 PATCH 方法时，流密钥共享存储区的内容。

Example:

{
  "key1" : "value1",
  "key2" : "value2",
  "key3" : {
    "value" : "value3",
    "expire" : 30000
  }
}

流区同步节点：
zones
- 每个共享内存区域的同步信息。

“ Sync Zone”对象的集合

status
- 集群中每个节点的同步信息。
bytes_in ( integer )
- 该节点接收的字节数。
- msgs_in ( integer )
  - 该节点接收到的消息数。
- msgs_out ( integer )
  - 该节点发送的消息数。
- bytes_out ( integer )
  - 此节点发送的字节数。
- nodes_online ( integer )
  - 该节点连接的对等体数。

Example:

{
  "zones" : {
    "zone1" : {
      "records_pending" : 2061,
      "records_total" : 260575
    },
    "zone2" : {
      "records_pending" : 0,
      "records_total" : 14749
    }
  },
  "status" : {
    "bytes_in" : 1364923761,
    "msgs_in" : 337236,
    "msgs_out" : 346717,
    "bytes_out" : 1402765472,
    "nodes_online" : 15
  }
}

Sync Zone:

共享内存区域的同步状态。

records_pending ( integer )
- 需要发送到集群的记录数。
records_total ( integer )
- 共享存储区中存储的记录总数。
Resolver Zone:

每个特定resolver zone的 DNS 请求和响应的统计信息。

requests
- - name ( integer )
  - 将名称解析为地址的请求总数。
- srv ( integer )
  - 解析 SRV 记录的请求总数。
- addr ( integer )
  - 将地址解析为名称的请求总数。
responses
- - noerror ( integer )
  - 成功响应的总数。
- formerr ( integer )
  - FORMERR(Format error)响应的总数。
- servfail ( integer )
  - SERVFAIL(Server failure)响应的总数。
- nxdomain ( integer )
  - NXDOMAIN(Host not found)响应的总数。
- notimp ( integer )
  - NOTIMP(Unimplemented)响应的总数。
- refused ( integer )
  - REFUSED(Operation refused)个响应的总数。
- timedout ( integer )
  - 超时请求总数。
- unknown ( integer )
  - 发生未知错误的请求总数。

Example:

{
  "resolver_zone1" : {
    "requests" : {
      "name" : 25460,
      "srv" : 130,
      "addr" : 2580
    },
    "responses" : {
      "noerror" : 26499,
      "formerr" : 0,
      "servfail" : 3,
      "nxdomain" : 0,
      "notimp" : 0,
      "refused" : 0,
      "timedout" : 243,
      "unknown" : 478
    }
  }
}

Error:

nginx 错误对象。

error
- - status ( integer )
  - HTTP 错误代码。
- text ( string )
  - Error description.
- code ( string )
  - 内部 Nginx 错误代码。
request_id ( string )
- 请求的 ID 等于$request_id变量的值。
href ( string )
- 链接到参考文档。

首页

Nginx 中文文档

Module ngx_http_api_module

Example Configuration

Directives

Compatibility

Endpoints

/

/nginx

/processes

/connections

/slabs/

/slabs/

/http/

/http/requests

/http/server_zones/

/http/server_zones/

/http/location_zones/

/http/location_zones/

/http/caches/

/http/caches/

/http/limit_conns/

/http/limit_conns/

/http/limit_reqs/

/http/limit_reqs/

/http/upstreams/

/http/upstreams//

/http/upstreams//servers/

/http/upstreams//servers/

/http/keyvals/

/http/keyvals/

/stream/

/stream/server_zones/

/stream/server_zones/

/stream/limit_conns/

/stream/limit_conns/

/stream/upstreams/

/stream/upstreams//

/stream/upstreams//servers/

/stream/upstreams//servers/

/stream/keyvals/

/stream/keyvals/

/stream/zone_sync/

/resolvers/

/resolvers/

/ssl

Response Objects