ngx_http_api_module

示例配置
指令
api
端点
/
/nginx
/进程
/链接
/ssl
/slabs/
/slabs/{slabZoneName}
/http/
/http/requests
/http/server_zones/
/http/server_zones/{httpServerZoneName}
/http/caches/
/http/caches/{httpCacheZoneName}
/http/upstreams/
/http/upstreams/{httpUpstreamName}/
/http/upstreams/{httpUpstreamName}/servers/
/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}
/http/keyvals/
/http/keyvals/{httpKeyvalZoneName}
/流/
/流/server_zones/
/流/server_zones/{streamServerZoneName}
/流/upstreams/
/流/upstreams/{streamUpstreamName}/
/流/upstreams/{streamUpstreamName}/servers/
//upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}
应答对象

所述ngx_http_api_module模块（1.13.3）提供REST API访问的各种状态信息，关于即时配置上游服务器组，并管理键-值对，而无需重新配置Nginx的。

该模块取代ngx_http_status_module和ngx_http_upstream_conf_module模块。此模块可作为我们商业订阅的一部分。

示例配置

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版本。使用此配置的API请求示例：

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

指令

句法：	api write = 开启\|关闭;
默认：	—
语境：	位置

打开周围位置的REST API接口。访问这个位置应该是有限的。

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

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

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

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

端点

/

支持的方法：

GET - 根端点返回列表返回根端点列表。可能的回应：

- 200 - Success, returns an array of strings

/nginx

支持的方法：

GET - 返回nginx运行实例的状态返回nginx版本，构建名称，地址，配置重新加载的数量，主进程和工作进程的ID。请求参数： fields（string，可选）限制了nginx的运行实例字段将被输出。可能的回应：

- 200 - Success, returns [nginx](about:blank#def_nginx_object)

/processes

支持的方法：

GET - 返回nginx进程状态返回异常终止和重新生成的子进程的数量。可能的回应：

- 200 - Success, returns [Processes](about:blank#def_nginx_processes)

DELETE - 重置nginx进程统计信息重置异常终止和重新生成的子进程的计数器。可能的回应：

- 204 - Success

/connections

支持的方法：

GET - 返回客户连接统计返回客户连接的统计。请求参数： fields（string，可选）限制所述连接的统计信息的字段将被输出。可能的回应：

- 200 - Success, returns [Connections](about:blank#def_nginx_connections)

DELETE - 重置客户端连接统计信息重置接受和丢弃的客户端连接的统计信息可能的回应：

- 204 - Success

/ssl

支持的方法：

GET - 返回SSL统计信息返回SSL统计信息。请求参数： fields（string，可选）限制了SSL统计领域将输出。可能的回应：

- 200 - Success, returns [SSL](about:blank#def_nginx_ssl_object)

DELETE - 重置SSL统计信息重置SSL握手和会话重用的计数器。可能的回应：

- 204 - Success

/slabs/

支持的方法：

GET - 返回所有板的状态使用板分配器返回每个共享内存区的板的状态。请求参数： fields（string，可选）限制了板坯区字段将被输出。如果“ fields”值为空，则只输出区域名称。可能的回应：

- 200 - Success, returns a collection of "[Shared memory zone with slab allocator](about:blank#def_nginx_slab_zone)" objects for all slabs

/slabs/{slabZoneName}共同为所有方法参数：slabZoneName（string，必需）与slab分配器共享存储器区域的名称。

支持的方法：

GET - 返回slab的状态用slab分配器返回特定共享内存区域的slab的状态。请求参数： fields（string，可选）限制了板坯区的字段将被输出。可能的回应：

- 200 - Success, returns [Shared memory zone with slab allocator](about:blank#def_nginx_slab_zone) 
- 404 - Slab not found (`SlabNotFound`), returns [Error](about:blank#def_nginx_error)

DELETE- 重置板块统计信息重置每个内存插槽的“ reqs”和“ fails”度量标准。可能的回应：

- 204 - Success
- 404 - Slab not found (`SlabNotFound`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error)

/http/

支持的方法：

GET - 返回HTTP相关端点列表返回第一级HTTP端点列表。可能的回应：

- 200 - Success, returns an array of strings

/http/requests

支持的方法：

GET - 返回HTTP请求统计信息返回客户端HTTP请求的状态。请求参数： fields（string，可选）限制了客户端的HTTP请求的统计数据字段将被输出。可能的回应：

- 200 - Success, returns [HTTP Requests](about:blank#def_nginx_http_requests)

DELETE - 重置HTTP请求统计信息重置总客户端HTTP请求的数量。可能的回应：

- 204 - Success
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error)

/http/server_zones/

支持的方法：

GET - 返回所有HTTP服务器区域的状态返回每个HTTP服务器区域的状态信息。请求参数： fields（string，可选）限制了服务器区域的字段将被输出。如果“ fields”值为空，则仅输出服务器区域名称。可能的回应：

- 200 - Success, returns a collection of "[HTTP Server Zone](about:blank#def_nginx_http_server_zone)" objects for all http server zones

/http/server_zones/{httpServerZoneName}通用于所有方法的参数：httpServerZoneName（string所需）的HTTP服务器区域的名称。

支持的方法：

GET - 返回HTTP服务器区域的状态返回特定HTTP服务器区域的状态。请求参数： fields（string，可选）限制了服务器区的字段将被输出。可能的回应：

- 200 - Success, returns [HTTP Server Zone](about:blank#def_nginx_http_server_zone) 
- 404 - Server zone not found (`ServerZoneNotFound`), returns [Error](about:blank#def_nginx_error)

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

- 204 - Success
- 404 - Server zone not found (`ServerZoneNotFound`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error)

/http/caches/

支持的方法：

GET- 返回所有缓存的状态返回由proxy_cache_path和其他*_cache_path指令配置的每个缓存的状态。请求参数： fields（string，可选）限制了缓存区的字段将被输出。如果“ fields”值为空，则只输出缓存区域的名称。可能的回应：

- 200 - Success, returns a collection of "[HTTP Cache](about:blank#def_nginx_http_cache)" objects for all http caches

/http/caches/{httpCacheZoneName}通用于所有方法的参数：httpCacheZoneName（string所需）的缓存区的名称。

支持的方法：

GET - 返回缓存的状态返回特定缓存的状态。请求参数： fields（string，可选）限制了缓存区的字段将被输出。可能的回应：

- 200 - Success, returns [HTTP Cache](about:blank#def_nginx_http_cache) 
- 404 - Cache not found (`CacheNotFound`), returns [Error](about:blank#def_nginx_error)

DELETE - 重置高速缓存统计信息重置特定高速缓存区域中高速缓存命中/未命中的统计信息。可能的回应：

- 204 - Success
- 404 - Cache not found (`CacheNotFound`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error)

/http/upstreams/

支持的方法：

GET - 返回所有HTTP上游服务器组的状态返回每个HTTP上游服务器组及其服务器的状态。请求参数： fields（string，可选）限制了上游服务器组的字段将被输出。如果“ fields”值为空，则仅输出上游名称。可能的回应：

- 200 - Success, returns a collection of "[HTTP Upstream](about:blank#def_nginx_http_upstream)" objects for all http upstreams

/http/upstreams/{httpUpstreamName}/共同为所有方法参数：httpUpstreamName（string所需）的HTTP上游服务器组的名称。

支持的方法：

GET - 返回HTTP上游服务器组的状态返回特定HTTP上游服务器组及其服务器的状态。请求参数： fields（string，可选）限制了上游服务器组的字段将被输出。可能的回应：

- 200 - Success, returns [HTTP Upstream](about:blank#def_nginx_http_upstream) 
- 400 - Upstream is static (`UpstreamStatic`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), returns [Error](about:blank#def_nginx_error)

DELETE - 重置HTTP上游服务器组的统计信息重置上游服务器组中每个上游服务器的统计信息和队列统计信息。可能的回应：

- 204 - Success
- 400 - Upstream is static (`UpstreamStatic`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error)

/http/upstreams/{httpUpstreamName}/servers/共同为所有方法参数：httpUpstreamName（string所需）的上游服务器组的名称。

支持的方法：

GET - 返回HTTP上游服务器组中所有服务器的配置返回特定HTTP上游服务器组中每个服务器的配置。可能的回应：

- 200 - Success, returns an array of [HTTP Upstream Servers](about:blank#def_nginx_http_upstream_conf_server) 
- 400 - Upstream is static (`UpstreamStatic`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), returns [Error](about:blank#def_nginx_error)

POST - 将服务器添加到HTTP上游服务器组将新服务器添加到HTTP上游服务器组。服务器参数以JSON格式指定。请求参数:( postHttpUpstreamServerHTTP上游服务器，必需）新服务器的地址和JSON格式的其他可选参数。“ ID”，“ backup”和“ service”参数不能更改。可能的回应：

- 201 - Created, returns [HTTP Upstream Server](about:blank#def_nginx_http_upstream_conf_server) 
- 400 - Upstream is static (`UpstreamStatic`), invalid “_`parameter`_” value (`UpstreamConfFormatError`), missing “`server`” argument (`UpstreamConfFormatError`), unknown parameter “_`name`_” (`UpstreamConfFormatError`), nested object or list (`UpstreamConfFormatError`), “`error`” while parsing (`UpstreamBadAddress`), service upstream “`host`” may not have port (`UpstreamBadAddress`), service upstream “`host`” requires domain name (`UpstreamBadAddress`), invalid “`weight`” (`UpstreamBadWeight`), invalid “`max_conns`” (`UpstreamBadMaxConns`), invalid “`max_fails`” (`UpstreamBadMaxFails`), invalid “`fail_timeout`” (`UpstreamBadFailTimeout`), invalid “`slow_start`” (`UpstreamBadSlowStart`), route is too long (`UpstreamBadRoute`), “`service`” is empty (`UpstreamBadService`), no resolver defined to resolve (`UpstreamConfNoResolver`), upstream “_`name`_” has no backup (`UpstreamNoBackup`), upstream “_`name`_” memory exhausted (`UpstreamOutOfMemory`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error) 
- 415 - JSON error (`JsonError`), returns [Error](about:blank#def_nginx_error)

/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}共同为所有方法参数：httpUpstreamName（string所需）上游服务器组的名称。httpUpstreamServerId（string，必填）服务器的ID。

支持的方法：

GET - 返回HTTP上游服务器组中服务器的配置返回HTTP上游服务器组中特定服务器的配置。可能的回应：

- 200 - Success, returns [HTTP Upstream Server](about:blank#def_nginx_http_upstream_conf_server) 
- 400 - Upstream is static (`UpstreamStatic`), invalid server ID (`UpstreamBadServerId`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), server with ID “_`id`_” does not exist (`UpstreamServerNotFound`), returns [Error](about:blank#def_nginx_error)

PATCH - 修改HTTP上游服务器组中的服务器修改HTTP上游服务器组中特定服务器的设置。服务器参数以JSON格式指定。请求参数:( patchHttpUpstreamServerHTTP上游服务器，必需）服务器参数，以JSON格式指定。“ ID”，“ backup”和“ service”参数不能更改。可能的回应：

- 200 - Success, returns [HTTP Upstream Server](about:blank#def_nginx_http_upstream_conf_server) 
- 400 - Upstream is static (`UpstreamStatic`), invalid “_`parameter`_” value (`UpstreamConfFormatError`), unknown parameter “_`name`_” (`UpstreamConfFormatError`), nested object or list (`UpstreamConfFormatError`), “`error`” while parsing (`UpstreamBadAddress`), invalid “`server`” argument (`UpstreamBadAddress`), invalid server ID (`UpstreamBadServerId`), invalid “`weight`” (`UpstreamBadWeight`), invalid “`max_conns`” (`UpstreamBadMaxConns`), invalid “`max_fails`” (`UpstreamBadMaxFails`), invalid “`fail_timeout`” (`UpstreamBadFailTimeout`), invalid “`slow_start`” (`UpstreamBadSlowStart`), route is too long (`UpstreamBadRoute`), “`service`” is empty (`UpstreamBadService`), server “_`ID`_” address is immutable (`UpstreamServerImmutable`), server “`ID`” weight is immutable (`UpstreamServerWeightImmutable`), upstream “`name`” memory exhausted (`UpstreamOutOfMemory`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), server with ID “_`id`_” does not exist (`UpstreamServerNotFound`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error) 
- 415 - JSON error (`JsonError`), returns [Error](about:blank#def_nginx_error)

DELETE - 从HTTP上游服务器组中删除服务器从HTTP上游服务器组中删除服务器。可能的回应：

- 200 - Success, returns an array of [HTTP Upstream Servers](about:blank#def_nginx_http_upstream_conf_server) 
- 400 - Upstream is static (`UpstreamStatic`), invalid server ID (`UpstreamBadServerId`), server “_`id`_” not removable (`UpstreamServerImmutable`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), server with ID “_`id`_” does not exist (`UpstreamServerNotFound`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error)

/http/keyvals/

支持的方法：

GET - 从所有keyval区域返回键值对每个keyval共享内存区域返回键值对。请求参数： fields（string，可选）如果“ fields”值为空，那么只有KEYVAL区名称输出。可能的回应：

- 200 - Success, returns a collection of "[Keyval Shared Memory Zone](about:blank#def_nginx_http_keyval_zone)" objects for all http keyvals

/http/keyvals/{httpKeyvalZoneName}共同为所有方法参数：httpKeyvalZoneName（string所需）一个KEYVAL共享存储器区域的名称。

支持的方法：

GET - 从keyval区域返回键值对返回存储在特定keyval共享内存区域中的键值对。请求参数： key（string，可选）获得从所述KEYVAL区一个特定的键-值对。可能的回应：

- 200 - Success, returns [Keyval Shared Memory Zone](about:blank#def_nginx_http_keyval_zone) 
- 404 - Keyval not found (`KeyvalNotFound`), keyval key not found (`KeyvalKeyNotFound`), returns [Error](about:blank#def_nginx_error)

POST - 向keyval区域添加键值对将新的键值对添加到keyval共享内存区域。如果keyval共享内存区域为空，则可以输入多个键值对。请求参数:( Key-valueKeyval Shared Memory Zone，必需）键值对以JSON格式指定。如果keyval共享内存区域为空，则可以输入多个键值对。可能的回应：

- 201 - Created
- 400 - Key required (`KeyvalFormatError`), only one key can be added (`KeyvalFormatError`), nested object or list (`KeyvalFormatError`), returns [Error](about:blank#def_nginx_error) 
- 404 - Keyval not found (`KeyvalNotFound`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error) 
- 409 - Key already exists (`KeyvalKeyExists`), returns [Error](about:blank#def_nginx_error) 
- 415 - JSON error (`JsonError`), returns [Error](about:blank#def_nginx_error)

PATCH- 修改键值或删除键更改键值对中所选键的值或通过将键值设置为来删除键null。请求参数： httpKeyvalZoneKeyValue（Keyval共享内存区域，必需）以JSON格式指定键的新值。可能的回应：

- 204 - Success
- 400 - Key required (`KeyvalFormatError`), only one key can be updated (`KeyvalFormatError`), nested object or list (`KeyvalFormatError`), returns [Error](about:blank#def_nginx_error) 
- 404 - Keyval not found (`KeyvalNotFound`), keyval key not found (`KeyvalKeyNotFound`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error) 
- 415 - JSON error (`JsonError`), returns [Error](about:blank#def_nginx_error)

DELETE - 清空keyval区域从keyval共享内存区域中删除所有键值对。可能的回应：

- 204 - Success
- 404 - Keyval not found (`KeyvalNotFound`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error)

/stream/

支持的方法：

GET - 与流相关的端点的返回列表返回第一级流终端列表。可能的回应：

- 200 - Success, returns an array of strings

/stream/server_zones/

支持的方法：

GET - 返回所有流服务器区域的状态返回每个流服务器区域的状态信息。请求参数： fields（string，可选）限制了服务器区域的字段将被输出。如果“ fields”值为空，则仅输出服务器区域名称。可能的回应：

- 200 - Success, returns a collection of "[Stream Server Zone](about:blank#def_nginx_stream_server_zone)" objects for all stream server zones 
- 404 - [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error)

/stream/server_zones/{streamServerZoneName}通用于所有方法的参数：streamServerZoneName（string所需）流服务器区域的名称。

支持的方法：

GET - 返回流服务器区域的状态返回特定流服务器区域的状态。请求参数： fields（string，可选）限制了服务器区的字段将被输出。可能的回应：

- 200 - Success, returns [Stream Server Zone](about:blank#def_nginx_stream_server_zone) 
- 404 - Server zone not found (`ServerZoneNotFound`), [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error)

DELETE - 重置流服务器区域的统计信息重置特定流服务器区域中接受和丢弃的连接，会话，接收和发送字节的统计信息。可能的回应：

- 204 - Success
- 404 - Server zone not found (`ServerZoneNotFound`), [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error)

/stream/upstreams/

支持的方法：

GET - 返回所有流上游服务器组的状态返回每个流上游服务器组及其服务器的状态。请求参数： fields（string，可选）限制了上游服务器组的字段将被输出。如果“ fields”值为空，则仅输出上游名称。可能的回应：

- 200 - Success, returns a collection of "[Stream Upstream](about:blank#def_nginx_stream_upstream)" objects for all stream upstreams 
- 404 - [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error)

/stream/upstreams/{streamUpstreamName}/共同为所有方法参数：streamUpstreamName（string所需）流上游服务器组的名称。

支持的方法：

GET - 返回流上游服务器组的状态返回特定流上游服务器组及其服务器的状态。请求参数： fields（string，可选）限制了上游服务器组的字段将被输出。可能的回应：

- 200 - Success, returns [Stream Upstream](about:blank#def_nginx_stream_upstream) 
- 400 - Upstream is static (`UpstreamStatic`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error)

DELETE - 重置流上游服务器组的统计信息重置上游服务器组中每个上游服务器的统计信息。可能的回应：

- 204 - Success
- 400 - Upstream is static (`UpstreamStatic`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error)

/stream/upstreams/{streamUpstreamName}/servers/共同为所有方法参数：streamUpstreamName（string所需）的上游服务器组的名称。

支持的方法：

GET - 返回流上游服务器组中所有服务器的配置返回特定流上游服务器组中每个服务器的配置。可能的回应：

- 200 - Success, returns an array of [Stream Upstream Servers](about:blank#def_nginx_stream_upstream_conf_server) 
- 400 - Upstream is static (`UpstreamStatic`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error)

POST - 将服务器添加到流上游服务器组，将新服务器添加到流上游服务器组。服务器参数以JSON格式指定。请求参数:( postStreamUpstreamServer流上游服务器，必需）新服务器的地址和JSON格式的其他可选参数。“ ID”，“ backup”和“ service”参数不能更改。可能的回应：

- 201 - Created, returns [Stream Upstream Server](about:blank#def_nginx_stream_upstream_conf_server) 
- 400 - Upstream is static (`UpstreamStatic`), invalid “_`parameter`_” value (`UpstreamConfFormatError`), missing “`server`” argument (`UpstreamConfFormatError`), unknown parameter “_`name`_” (`UpstreamConfFormatError`), nested object or list (`UpstreamConfFormatError`), “`error`” while parsing (`UpstreamBadAddress`), no port in server “`host`” (`UpstreamBadAddress`), service upstream “`host`” may not have port (`UpstreamBadAddress`), service upstream “`host`” requires domain name (`UpstreamBadAddress`), invalid “`weight`” (`UpstreamBadWeight`), invalid “`max_conns`” (`UpstreamBadMaxConns`), invalid “`max_fails`” (`UpstreamBadMaxFails`), invalid “`fail_timeout`” (`UpstreamBadFailTimeout`), invalid “`slow_start`” (`UpstreamBadSlowStart`), “`service`” is empty (`UpstreamBadService`), no resolver defined to resolve (`UpstreamConfNoResolver`), upstream “_`name`_” has no backup (`UpstreamNoBackup`), upstream “_`name`_” memory exhausted (`UpstreamOutOfMemory`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error) 
- 415 - JSON error (`JsonError`), returns [Error](about:blank#def_nginx_error)

/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}共同为所有方法参数：streamUpstreamName（string所需）上游服务器组的名称。streamUpstreamServerId（string，必填）服务器的ID。

支持的方法：

GET - 返回流上游服务器组中服务器的配置返回流上游服务器组中特定服务器的配置。可能的回应：

- 200 - Success, returns [Stream Upstream Server](about:blank#def_nginx_stream_upstream_conf_server) 
- 400 - Upstream is static (`UpstreamStatic`), invalid server ID (`UpstreamBadServerId`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), server with ID “_`id`_” does not exist (`UpstreamServerNotFound`), [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error)

PATCH - 修改流上游服务器组中的服务器，修改流上游服务器组中特定服务器的设置。服务器参数以JSON格式指定。请求参数:( patchStreamUpstreamServer流上游服务器，必需）服务器参数，以JSON格式指定。“ ID”，“ backup”和“ service”参数不能更改。可能的回应：

- 200 - Success, returns [Stream Upstream Server](about:blank#def_nginx_stream_upstream_conf_server) 
- 400 - Upstream is static (`UpstreamStatic`), invalid “_`parameter`_” value (`UpstreamConfFormatError`), unknown parameter “_`name`_” (`UpstreamConfFormatError`), nested object or list (`UpstreamConfFormatError`), “`error`” while parsing (`UpstreamBadAddress`), invalid “`server`” argument (`UpstreamBadAddress`), no port in server “`host`” (`UpstreamBadAddress`), invalid server ID (`UpstreamBadServerId`), invalid “`weight`” (`UpstreamBadWeight`), invalid “`max_conns`” (`UpstreamBadMaxConns`), invalid “`max_fails`” (`UpstreamBadMaxFails`), invalid “`fail_timeout`” (`UpstreamBadFailTimeout`), invalid “`slow_start`” (`UpstreamBadSlowStart`), “`service`” is empty (`UpstreamBadService`), server “_`ID`_” address is immutable (`UpstreamServerImmutable`), server “_`ID`_” weight is immutable (`UpstreamServerWeightImmutable`), upstream “`name`” memory exhausted (`UpstreamOutOfMemory`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), server with ID “_`id`_” does not exist (`UpstreamServerNotFound`), [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error) 
- 415 - JSON error (`JsonError`), returns [Error](about:blank#def_nginx_error)

DELETE - 从流上游服务器组中删除服务器，从流服务器组中删除服务器。可能的回应：

- 200 - Success, returns an array of [Stream Upstream Servers](about:blank#def_nginx_stream_upstream_conf_server) 
- 400 - Upstream is static (`UpstreamStatic`), invalid server ID (`UpstreamBadServerId`), server “_`id`_” not removable (`UpstreamServerImmutable`), returns [Error](about:blank#def_nginx_error) 
- 404 - Upstream not found (`UpstreamNotFound`), server with ID “_`id`_” does not exist (`UpstreamServerNotFound`), [stream](../stream/ngx_stream_core_module#stream) not configured (`StreamNotConfigured`), returns [Error](about:blank#def_nginx_error) 
- 405 - Method disabled (`MethodDisabled`), returns [Error](about:blank#def_nginx_error)

响应对象

nginx：关于nginx的一般信息 version（string）Nginx的版本。 build（string）nginx构建的名称。 address（string）接受状态请求的服务器地址。 generation（integer）配置重新加载的总数。 load_timestamp（string）最后一次重新载入配置的时间，以Epoch以来的毫秒数表示。 timestamp（string）Epoch以来的当前时间（以毫秒为单位）。 pid（integer）处理状态请求的工作进程的ID。 ppid（integer）启动辅助进程的主进程的标识。例如：{“nginx”：{“version”：“1.13.3”，“build”：“nginx-plus-r12-p3”，“address”：“206.251.255.64”，“generation”：2，“load_timestamp “：”2017-07-07T11：09：21.594Z“，”timestamp“：”2017-07-11T09：31：13.477Z“，”pid“：32212，”ppid“：32210}}
过程： respawned（integer）异常终止和重生子进程的总数。例如：{“respawned”：0}
连接数：接受，丢弃，活动和空闲连接的数量。 accepted（integer）接受的客户端连接的总数。 dropped（integer）丢弃的客户端连接的总数。 active（integer）当前活动的客户端连接数。 idle（integer）当前空闲的客户端连接数。例如：{“accepted”：4968119，“dropped”：0，“active”：5，“idle”：117}
SSL：（ handshakes）integer成功的SSL握手的总数。 handshakes_failed（integer）失败的SSL握手的总数。 session_reuses（integer）SSL握手期间会话??重用的总次数。例如：{“handshakes”：79572，“handshakes_failed”：21025，“session_reuses”：15762}
与slab分配器共享的内存区域： pages 可用和已用内存页面的数量。 used（integer）当前使用的内存页数。 free（integer）当前的可用内存页数。 slots 内存插槽的状态数据（8,16,32,64,128等）“Memory Slot”对象的集合示例：{“pages”：{“used”：1143，“free”：2928}，“slots “：{”8“：{”used“：0，”free“：0，”reqs“：0，”failed“：0}，”16“：{”used“：0，”free“ “reqs”：0，“failed”：0}，“32”：{“used”：0，“free”：0，“reqs”：0，“failed”：0}，“64”：{“used “：1，”free“：63，”reqs“：1，”failed“：0}，”128“：{”used“：0，“free”：0，“reqs”：0，“failed”：0}，“256”：{“used”：18078，“free”：178，“reqs”：1635736，“failed”：0}}}
存储器插槽： used（integer）使用的存储器插槽的当前数目。 free（integer）当前可用内存插槽的数量。 reqs（integer）尝试分配指定大小的内存的总次数。 fails（integer）尝试分配指定大小的内存失败的次数。
HTTP请求： total（integer）的客户端请求的总数。 current（integer）当前的客户端请求数。例如：{“total”：10624511，“current”：4}
HTTP服务器区： processing（integeri）目前正在处理的客户端请求数。 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）发送给客户端的总字节数。示例：{“processing”：1，“requests”：706690，“responses”：{“1xx”：0，“2xx”：699482，“3xx”：4522，“4xx”：907，“5xx” “total”：705177}，“discarded”：1513，“received”：172711587，“sent”：19415530115}
HTTP缓存： size（integer）高速缓存的当前大小。 max_size（integer）配置中指定的缓存的最大大小限制。 cold（boolean）一个布尔值，指示“缓存加载器”进程是否仍在将数据从磁盘加载到缓存中。 hit responses（integer）从缓存中读取的有效响应总数。 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）写入缓存的总字节数。例如：{“size”：530915328，“max_size”：536870912，“cold”：false，“hit”：{“responses”：254032，“bytes”：6685627875}，“stale”：{“responses” “bytes”：0}，“updates”：{“responses”：0，“bytes”：0}，“revalidated”：{“responses”：0，“bytes”：0}，“miss”：{ “：”1619201，“bytes”：53841943822}，“expired”：{“responses”：45859，“bytes”：1656847080，“responses_written”：44992，“bytes_written”：1641825173}
HTTP上游： peers 数组： id（integer）的服务器的ID。 server（string）服务器的地址。 service（string）服务器指令的服务参数值。 name（string）服务器指令中指定的服务器的名称。 backup（boolean）指示服务器是否为备份服务器的布尔值。 weight（integer）服务器的权重。 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）unavail由于达到max_fails阈值的失败尝试次数，服务器因客户端请求（状态“ ”）而变得不可用的次数。 health_checks checks（integer）健康检查请求的总数。 fails（integer）健康检查失败的次数。 unhealthy（integer）服务器变得不健康多少次（状态“ unhealthy”）。 last_passed（boolean）布尔值，指示最后的运行状况检查请求是否成功并通过了测试。 downtime（integer）服务器处于“ unavail”，“ checking”和“ unhealthy”状态的总时间。 downstart（string）服务器变成“ unavail”，“ checking”或“ unhealthy” 的时间（自Epoch以来的毫秒数）。 selected（string）上次选择服务器处理请求时的时间（自Epoch起，以毫秒为单位）。 header_time（integer）从服务器获取响应头的平均时间。 response_time（integer）从服务器获得完整响应的平均时间。 keepalive（integer）当前空闲保持连接的数量。 zombies（integer）当前从组中删除的服务器数量，但仍处理活动客户端请求。 zone（string）保持组的配置和运行时状态的共享内存区域的名称。 queue 对于请求队列中，提供以下数据： size（integer）在队列中的请求的当前数目。 max_size（integer）同时可以在队列中的最大请求数。 overflows（integer）由于队列溢出而被拒绝的请求总数。示例：{“upstream_backend”：{“peers”：{“id”：0，“server”：“10.0.0.1:8088”，“name”：“10.0.0.1:8088”，“backup”：false，“体重“：5，”状态“：”上“，”活动“：0，”max_conns“：20，”请求“：667231，”header_time“：20，”response_time“：36，”responses“：{”1xx “：0，”2xx“：666310，”3xx“：0，”4xx“：915，”5xx“：6，”总计“：667231}，”发送“：
HTTP上游服务器：动态的HTTP上游服务器的配置的参数： id（integer）的HTTP上游服务器的ID。该ID是自动分配的，不能更改。 server（string）与HTTP上游服务器的地址参数相同。添加服务器时，可以将其指定为域名。在这种情况下，与域名对应的IP地址的更改将被监控并自动应用到上游配置，而无需重新启动nginx。这需要“ http”块中的解析器指令。另请参阅HTTP上游服务器的resolve参数。 service（string）与HTTP上游服务器的服务参数相同。该参数不能更改。 weight（integer）与HTTP上游服务器的权重参数相同。 max_conns（integer）与HTTP上游服务器的max_conns参数相同。 max_fails（integer）与HTTP上游服务器的max_fails参数相同。 fail_timeout（integer）与HTTP上游服务器的fail_timeout参数相同。 slow_start（integer）与HTTP上游服务器的slow_start参数相同。 route（string）与HTTP上游服务器的路由参数相同。 backup（boolean）何时true添加备份服务器。该参数不能更改。 down（boolean）与HTTP上游服务器的down参数相同。 parent（string）已解析服务器的父级服务器标识。该ID是自动分配的，不能更改。 host（string）已解析服务器的主机名。主机名是自动分配的，不能更改。 drain（string）将HTTP上游服务器置于“排空”模式。在这种模式下，只有绑定到服务器的请求才会被代理。该参数不能初始设置，只能使用该PATCH方法更改。示例：{“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}
Keyval Shared Memory Zone：keyval shared memory zone的内容。例如：{“key1”：“value1”，“key2”：“value2”，“key3”：“value3”}
流服务器区域： processing（integer）当前正在处理的客户端连接的数量。 connections（integer）从客户端接受的连接总数。 sessions 完成的会话总数以及使用状态代码“ 2xx”，“ 4xx”或“ 5xx” 完成的会话数。 2xx（integer）用状态码“ 2xx” 完成的会话总数。 4xx（integer）用状态码“ 4xx” 完成的会话总数。 5xx（integer）用状态码“ 5xx” 完成的会话总数。 total（integer）完成的客户端会话总数。 discarded（integer）没有创建会话的连接总数。 received（integer）从客户端收到的总字节数。 sent（integer）发送给客户端的总字节数。示例：{“dns”：{“processing”：1，“connections”：155569，“sessions”：{“2xx”：155564，“4xx”：0，“5xx”：0，“total”：155569}， “丢弃”：0，“收到”：4200363，“发送”：20489184}}
流上游： peers 数组： id（integer）的服务器的ID。 server（string）服务器的地址。 service（string）服务器指令的服务参数值。 name（string）服务器指令中指定的服务器的名称。 backup（boolean）指示服务器是否为备份服务器的布尔值。 weight（integer）服务器的权重。 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）unavail由于达到max_fails阈值的失败尝试次数，服务器因为客户端连接（状态“ ”）而变得不可用的次数。 health_checks checks（integer）进行的健康检查请求总数。 fails（integer）健康检查失败的次数。 unhealthy（integer）服务器变得不健康多少次（状态“ unhealthy”）。 last_passed（boolean）布尔值，指示最后的运行状况检查请求是否成功并通过了测试。 downtime（integer）服务器处于“ unavail”，“ checking”和“ unhealthy”状态的总时间。 downstart（string）服务器变为“ unavail”，“ checking”或“ unhealthy” 时的时间（从Epoch开始以毫秒为单位）。 selected（string）上次选择服务器处理连接时的时间（自Epoch以来的毫秒数）。 zombies（integer）当前从组中删除的服务器数量，但仍处理活动客户端连接。 zone（string）保持组的配置和运行时状态的共享内存区域的名称。示例：{“dns”：{“peers”：{“id”：0，“server”：“10.0.0.1:12347”，“name”：“10.0.0.1:12347”，“backup”：false，“体重“：5，”状态“：”上“，”活动“：0，”max_conns“：50，”连接“：667231，”发送“：251946292，”收到“：19222475454，”失败“ unavail“：0，”health_checks“：{”checks“：26214，”failed“：0，”unhealthy“：0，”last_passed“：
流上游服务器：动态流上游服务器的配置的参数： id（integer）的流上游服务器的ID。该ID是自动分配的，不能更改。 server（string）与流上游服务器的地址参数相同。添加服务器时，可以将其指定为域名。在这种情况下，与域名对应的IP地址的更改将被监控并自动应用到上游配置，而无需重新启动nginx。这需要“ stream”块中的解析器指令。另请参阅流上游服务器的resolve参数。 service（string）与流上游服务器的服务参数相同。该参数不能更改。 weight（integer）与流上游服务器的权重参数相同。 max_conns（integer）与流上游服务器的max_conns参数相同。 max_fails（integer）与流上游服务器的max_fails参数相同。 fail_timeout（integer）与流上游服务器的fail_timeout参数相同。 slow_start（integer）与流上游服务器的slow_start参数相同。 backup（boolean）何时true添加备份服务器。该参数不能更改。 down（boolean）与流上游服务器的down参数相同。 parent（string）已解析服务器的父级服务器标识。该ID是自动分配的，不能更改。 host（string）已解析服务器的主机名。主机名是自动分配的，不能更改。例如：{“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}
错误：nginx错误对象。 path（string）API路径。 method（string）HTTP方法。 error status（string）HTTP错误代码。 text（string）错误描述。 code（string）内部nginx错误代码。 request_id（string）请求的ID等于$ request_id变量的值。 href（string）链接到参考文档。

本文档系腾讯云开发者社区成员共同维护，如有问题请联系 cloudcommunity@tencent.com

最后更新于：2017-12-18