wbtiger
/
ByConity
mirror of https://github.com/ByConity/ByConity
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

modify doc for custom http

This commit is contained in:
tai 2020-04-29 12:39:22 +08:00
parent cef5f12186
commit 89820f3458
1 changed files with 251 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

364
docs/en/interfaces/http.md
View File

@ -295,42 +295,44 @@ ClickHouse also supports Predefined HTTP Interface which can help you more easy
Example: Example:
- First of all, add this section to server configuration file: * First of all, add this section to server configuration file:
<!-- -->
``` xml ``` xml
<http_handlers> <http_handlers>
<predefine_query_handler> <rule>
<url>/metrics</url> <url>/predefine_query</url>
<method>GET</method> <methods>POST,GET</methods>
<queries> <handler>
<type>predefine_query_handler</type>
<query>SELECT * FROM system.metrics LIMIT 5 FORMAT Template SETTINGS format_template_resultset = 'prometheus_template_output_format_resultset', format_template_row = 'prometheus_template_output_format_row', format_template_rows_between_delimiter = '\n'</query> <query>SELECT * FROM system.metrics LIMIT 5 FORMAT Template SETTINGS format_template_resultset = 'prometheus_template_output_format_resultset', format_template_row = 'prometheus_template_output_format_row', format_template_rows_between_delimiter = '\n'</query>
</queries> </handler>
</predefine_query_handler> </rule>
<rule>...</rule>
<rule>...</rule>
</http_handlers> </http_handlers>
``` ```
- You can now request the url directly for data in the Prometheus format: * You can now request the url directly for data in the Prometheus format:
<!-- -->
``` bash ``` bash
curl -vvv 'http://localhost:8123/metrics' $ curl -v 'http://localhost:8123/predefine_query'
* Trying ::1... * Trying ::1...
* Connected to localhost (::1) port 8123 (#0) * Connected to localhost (::1) port 8123 (#0)
> GET /metrics HTTP/1.1 > GET /predefine_query HTTP/1.1
> Host: localhost:8123 > Host: localhost:8123
> User-Agent: curl/7.47.0 > User-Agent: curl/7.47.0
> Accept: */* > Accept: */*
> >
< HTTP/1.1 200 OK < HTTP/1.1 200 OK
< Date: Wed, 27 Nov 2019 08:54:25 GMT < Date: Tue, 28 Apr 2020 08:52:56 GMT
< Connection: Keep-Alive < Connection: Keep-Alive
< Content-Type: text/plain; charset=UTF-8 < Content-Type: text/plain; charset=UTF-8
< X-ClickHouse-Server-Display-Name: i-tl62qd0o < X-ClickHouse-Server-Display-Name: i-mloy5trc
< Transfer-Encoding: chunked < Transfer-Encoding: chunked
< X-ClickHouse-Query-Id: f39235f6-6ed7-488c-ae07-c7ceafb960f6 < X-ClickHouse-Query-Id: 96fe0052-01e6-43ce-b12a-6b7370de6e8a
< X-ClickHouse-Format: Template
< X-ClickHouse-Timezone: Asia/Shanghai
< Keep-Alive: timeout=3 < Keep-Alive: timeout=3
< X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"} < X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"}
< <
@ -355,155 +357,267 @@ curl -vvv 'http://localhost:8123/metrics'
"ReplicatedSend" 0 "ReplicatedSend" 0
* Connection #0 to host localhost left intact * Connection #0 to host localhost left intact
* Connection #0 to host localhost left intact
``` ```
As you can see from the example, if `<http_handlers>` is configured in the config.xml file, ClickHouse will match the HTTP requests received to the predefined type in `<http_handlers>`, then ClickHouse will execute the corresponding predefined query if the match is successful. As you can see from the example, if `<http_handlers>` is configured in the config.xml file and `<http_handlers>` can contain many `<rule>s`. ClickHouse will match the HTTP requests received to the predefined type in `<rule>` and the first matched runs the handler. Then ClickHouse will execute the corresponding predefined query if the match is successful.
Now `<http_handlers>` can configure `<root_handler>`, `<ping_handler>`, `<replicas_status_handler>`, `<dynamic_query_handler>` and `<no_handler_description>` . > Now `<rule>` can configure `<method>`, `<headers>`, `<url>`,`<handler>`:
> `<method>` is responsible for matching the method part of the HTTP request. `<method>` fully conforms to the definition of [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) in the HTTP protocol. It is an optional configuration. If it is not defined in the configuration file, it does not match the method portion of the HTTP request.
>
> `<url>` is responsible for matching the url part of the HTTP request. It is compatible with [RE2](https://github.com/google/re2)'s regular expressions. It is an optional configuration. If it is not defined in the configuration file, it does not match the url portion of the HTTP request.
>
> `<headers>` is responsible for matching the header part of the HTTP request. It is compatible with RE2's regular expressions. It is an optional configuration. If it is not defined in the configuration file, it does not match the header portion of the HTTP request.
>
>`<handler>` contains the main processing part. Now `<handler>` can configure `<type>`, `<status>`, ` <content_type>`, `<response_content>`, `<query>`, `<query_param_name>`.
> > `<type>` currently supports three types: **predefined_query_handler**, **dynamic_query_handler**, **static**.
> >
> > `<query>` - use with predefined_query_handler type, executes query when the handler is called.
> >
> > `<query_param_name>` - use with dynamic_query_handler type, extracts and executes the value corresponding to the <query_param_name> value in HTTP request params.
> >
> > `<status>` - use with static type, response status code.
> >
> > ` <content_type>` - use with static type, response [content-type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type).
> >
> > `<response_content>` - use with static type, Response content sent to client, when using the prefix 'file://' or 'config://', find the content from the file or configuration send to client.
## root\_handler {#root_handler} Next are the configuration methods for the different `<type>`.
`<root_handler>` returns the specified content for the root path request. The specific return content is configured by `http_server_default_response` in config.xml. if not specified, return **Ok.** ## predefined_query_handler
`http_server_default_response` is not defined and an HTTP request is sent to ClickHouse. The result is as follows: `<predefined_query_handler>` supports setting Settings and query_params values. You can configure `<query>` in the type of `<predefined_query_handler>`.
``` xml `<query>` value is a predefined query of `<predefined_query_handler>`, which is executed by ClickHouse when an HTTP request is matched and the result of the query is returned. It is a must configuration.
<http_handlers>
<root_handler/>
</http_handlers>
```
$ curl 'http://localhost:8123'
Ok.
`http_server_default_response` is defined and an HTTP request is sent to ClickHouse. The result is as follows:
``` xml
<http_server_default_response><![CDATA[<html ng-app="SMI2"><head><base href="http://ui.tabix.io/"></head><body><div ui-view="" class="content-ui"></div><script src="http://loader.tabix.io/master.js"></script></body></html>]]></http_server_default_response>
<http_handlers>
<root_handler/>
</http_handlers>
```
$ curl 'http://localhost:8123'
<html ng-app="SMI2"><head><base href="http://ui.tabix.io/"></head><body><div ui-view="" class="content-ui"></div><script src="http://loader.tabix.io/master.js"></script></body></html>%
## ping\_handler {#ping_handler}
`<ping_handler>` can be used to probe the health of the current ClickHouse Server. When the ClickHouse HTTP Server is normal, accessing ClickHouse through `<ping_handler>` will return **Ok.**.
Example:
``` xml
<http_handlers>
<ping_handler>/ping</ping_handler>
</http_handlers>
```
``` bash
$ curl 'http://localhost:8123/ping'
Ok.
```
## replicas\_status\_handler {#replicas_status_handler}
`<replicas_status_handler>` is used to detect the state of the replica node and return **Ok.** if the replica node has no delay. If there is a delay, return the specific delay. The value of `<replicas_status_handler>` supports customization. If you do not specify `<replicas_status_handler>`, ClickHouse default setting `<replicas_status_handler>` is **/replicas\_status**.
Example:
``` xml
<http_handlers>
<replicas_status_handler>/replicas_status</replicas_status_handler>
</http_handlers>
```
No delay case:
``` bash
$ curl 'http://localhost:8123/replicas_status'
Ok.
```
Delayed case:
``` bash
$ curl 'http://localhost:8123/replicas_status'
db.stats: Absolute delay: 22. Relative delay: 22.
```
## predefined\_query\_handler {#predefined_query_handler}
You can configure `<method>`, `<headers>`, `<url>` and `<queries>` in `<predefined_query_handler>`.
`<method>` is responsible for matching the method part of the HTTP request. `<method>` fully conforms to the definition of [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) in the HTTP protocol. It is an optional configuration. If it is not defined in the configuration file, it does not match the method portion of the HTTP request
`<url>` is responsible for matching the url part of the HTTP request. It is compatible with [RE2](https://github.com/google/re2)’s regular expressions. It is an optional configuration. If it is not defined in the configuration file, it does not match the url portion of the HTTP request
`<headers>` is responsible for matching the header part of the HTTP request. It is compatible with RE2’s regular expressions. It is an optional configuration. If it is not defined in the configuration file, it does not match the header portion of the HTTP request
`<queries>` value is a predefined query of `<predefined_query_handler>`, which is executed by ClickHouse when an HTTP request is matched and the result of the query is returned. It is a must configuration.
`<predefined_query_handler>` supports setting Settings and query\_params values.
The following example defines the values of `max_threads` and `max_alter_threads` settings, then queries the system table to check whether these settings were set successfully. The following example defines the values of `max_threads` and `max_alter_threads` settings, then queries the system table to check whether these settings were set successfully.
Example: Example:
``` xml ``` xml
<root_handlers> <http_handlers>
<predefined_query_handler> <rule>
<url><![CDATA[/query_param_with_url/\w+/(?P<name_1>[^/]+)(/(?P<name_2>[^/]+))?]]></url>
<method>GET</method> <method>GET</method>
<headers> <headers>
<XXX>TEST_HEADER_VALUE</XXX> <XXX>TEST_HEADER_VALUE</XXX>
<PARAMS_XXX><![CDATA[(?P<name_1>[^/]+)(/(?P<name_2>[^/]+))?]]></PARAMS_XXX> <PARAMS_XXX><![CDATA[(?P<name_1>[^/]+)(/(?P<name_2>[^/]+))?]]></PARAMS_XXX>
</headers> </headers>
<url><![CDATA[/query_param_with_url/\w+/(?P<name_1>[^/]+)(/(?P<name_2>[^/]+))?]]></url> <handler>
<queries> <type>predefine_query_handler</type>
<query>SELECT value FROM system.settings WHERE name = {name_1:String}</query> <query>SELECT value FROM system.settings WHERE name = {name_1:String}</query>
<query>SELECT name, value FROM system.settings WHERE name = {name_2:String}</query> <query>SELECT name, value FROM system.settings WHERE name = {name_2:String}</query>
</queries> </handler>
</predefined_query_handler> </rule>
</root_handlers> </http_handlers>
``` ```
``` bash ``` bash
$ curl -H 'XXX:TEST_HEADER_VALUE' -H 'PARAMS_XXX:max_threads' 'http://localhost:8123/query_param_with_url/1/max_threads/max_alter_threads?max_threads=1&max_alter_threads=2' $ curl -H 'XXX:TEST_HEADER_VALUE' -H 'PARAMS_XXX:max_threads' 'http://localhost:8123/query_param_with_url/1/max_threads/max_alter_threads?max_threads=1&max_alter_threads=2'
1 1
max_alter_threads 2 max_alter_threads 2
``` ```
!!! note "Note" !!! note "caution"
In one `<predefined_query_handler>`, one `<queries>` only supports one `<query>` of an insert type. In one `<predefined_query_handler>` only supports one `<query>` of an insert type.
## dynamic\_query\_handler {#dynamic_query_handler} ## dynamic_query_handler
`<dynamic_query_handler>` than `<predefined_query_handler>` increased `<query_param_name>` . In `<dynamic_query_handler>`, query is written in the form of param of the HTTP request. The difference is that in `<predefined_query_handler>`, query is wrote in the configuration file. You can configure `<query_param_name>` in `<dynamic_query_handler>`.
ClickHouse extracts and executes the value corresponding to the `<query_param_name>` value in the url of the HTTP request. ClickHouse extracts and executes the value corresponding to the `<query_param_name>` value in the url of the HTTP request. The default value of `<query_param_name>` is `/query` . It is an optional configuration. If there is no definition in the configuration file, the param is not passed in.
ClickHouse default setting `<query_param_name>` is `/query` . It is an optional configuration. If there is no definition in the configuration file, the param is not passed in.
To experiment with this functionality, the example defines the values of max\_threads and max\_alter\_threads and queries whether the Settings were set successfully. To experiment with this functionality, the example defines the values of max_threads and max_alter_threads and queries whether the Settings were set successfully.
The difference is that in `<predefined_query_handler>`, query is wrote in the configuration file. But in `<dynamic_query_handler>`, query is written in the form of param of the HTTP request.
Example: Example:
``` xml ``` xml
<root_handlers> <http_handlers>
<dynamic_query_handler> <rule>
<headers> <headers>
<XXX>TEST_HEADER_VALUE_DYNAMIC</XXX> <XXX>TEST_HEADER_VALUE_DYNAMIC</XXX> </headers>
<PARAMS_XXX><![CDATA[(?P<param_name_1>[^/]+)(/(?P<param_name_2>[^/]+))?]]></PARAMS_XXX> <handler>
</headers> <type>dynamic_query_handler</type>
<query_param_name>query_param</query_param_name> <query_param_name>query_param</query_param_name>
</dynamic_query_handler> </handler>
</root_handlers> </rule>
</http_handlers>
``` ```
``` bash ``` bash
$ curl -H 'XXX:TEST_HEADER_VALUE_DYNAMIC' -H 'PARAMS_XXX:max_threads' 'http://localhost:8123/?query_param=SELECT%20value%20FROM%20system.settings%20where%20name%20=%20%7Bname_1:String%7D%20OR%20name%20=%20%7Bname_2:String%7D&max_threads=1&max_alter_threads=2&param_name_2=max_alter_threads' $ curl -H 'XXX:TEST_HEADER_VALUE_DYNAMIC' 'http://localhost:8123/own?max_threads=1&max_alter_threads=2&param_name_1=max_threads&param_name_2=max_alter_threads&query_param=SELECT%20name,value%20FROM%20system.settings%20where%20name%20=%20%7Bname_1:String%7D%20OR%20name%20=%20%7Bname_2:String%7D'
1 max_threads 1
2 max_alter_threads 2
```
## static
`<static>` can return [content_type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type), [status](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) and response_content. response_content can return the specified content
Example:
Return a message.
``` xml
<http_handlers>
<rule>
<methods>GET</methods>
<headers><XXX>xxx</XXX></headers>
<url>/hi</url>
<handler>
<type>static</type>
<status>402</status>
<content_type>text/html; charset=UTF-8</content_type>
<response_content>Say Hi!</response_content>
</handler>
</rule>
<http_handlers>
```
``` bash
$ curl -vv -H 'XXX:xxx' 'http://localhost:8123/hi'
* Trying ::1...
* Connected to localhost (::1) port 8123 (#0)
> GET /hi HTTP/1.1
> Host: localhost:8123
> User-Agent: curl/7.47.0
> Accept: */*
> XXX:xxx
>
< HTTP/1.1 402 Payment Required
< Date: Wed, 29 Apr 2020 03:51:26 GMT
< Connection: Keep-Alive
< Content-Type: text/html; charset=UTF-8
< Transfer-Encoding: chunked
< Keep-Alive: timeout=3
< X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"}
<
* Connection #0 to host localhost left intact
Say Hi!%
```
Find the content from the configuration send to client.
``` xml
<get_config_static_handler><![CDATA[<html ng-app="SMI2"><head><base href="http://ui.tabix.io/"></head><body><div ui-view="" class="content-ui"></div><script src="http://loader.tabix.io/master.js"></script></body></html>]]></get_config_static_handler>
<http_handlers>
<rule>
<methods>GET</methods>
<headers><XXX>xxx</XXX></headers>
<url>/get_config_static_handler</url>
<handler>
<type>static</type>
<response_content>config://get_config_static_handler</response_content>
</handler>
</rule>
</http_handlers>
```
``` bash
$ curl -v -H 'XXX:xxx' 'http://localhost:8123/get_config_static_handler'
* Trying ::1...
* Connected to localhost (::1) port 8123 (#0)
> GET /get_config_static_handler HTTP/1.1
> Host: localhost:8123
> User-Agent: curl/7.47.0
> Accept: */*
> XXX:xxx
>
< HTTP/1.1 200 OK
< Date: Wed, 29 Apr 2020 04:01:24 GMT
< Connection: Keep-Alive
< Content-Type: text/plain; charset=UTF-8
< Transfer-Encoding: chunked
< Keep-Alive: timeout=3
< X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"}
<
* Connection #0 to host localhost left intact
<html ng-app="SMI2"><head><base href="http://ui.tabix.io/"></head><body><div ui-view="" class="content-ui"></div><script src="http://loader.tabix.io/master.js"></script></body></html>%
```
Find the content from the file send to client.
``` xml
<http_handlers>
<rule>
<methods>GET</methods>
<headers><XXX>xxx</XXX></headers>
<url>/get_absolute_path_static_handler</url>
<handler>
<type>static</type>
<content_type>text/html; charset=UTF-8</content_type>
<response_content>file:///absolute_path_file.html</response_content>
</handler>
</rule>
<rule>
<methods>GET</methods>
<headers><XXX>xxx</XXX></headers>
<url>/get_relative_path_static_handler</url>
<handler>
<type>static</type>
<content_type>text/html; charset=UTF-8</content_type>
<response_content>file://./relative_path_file.html</response_content>
</handler>
</rule>
</http_handlers>
```
``` bash
$ user_files_path='/var/lib/clickhouse/user_files'
$ sudo echo "<html><body>Relative Path File</body></html>" > $user_files_path/relative_path_file.html
$ sudo echo "<html><body>Absolute Path File</body></html>" > $user_files_path/absolute_path_file.html
$ curl -vv -H 'XXX:xxx' 'http://localhost:8123/get_absolute_path_static_handler'
* Trying ::1...
* Connected to localhost (::1) port 8123 (#0)
> GET /get_absolute_path_static_handler HTTP/1.1
> Host: localhost:8123
> User-Agent: curl/7.47.0
> Accept: */*
> XXX:xxx
>
< HTTP/1.1 200 OK
< Date: Wed, 29 Apr 2020 04:18:16 GMT
< Connection: Keep-Alive
< Content-Type: text/html; charset=UTF-8
< Transfer-Encoding: chunked
< Keep-Alive: timeout=3
< X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"}
<
<html><body>Absolute Path File</body></html>
* Connection #0 to host localhost left intact
$ curl -vv -H 'XXX:xxx' 'http://localhost:8123/get_relative_path_static_handler'
* Trying ::1...
* Connected to localhost (::1) port 8123 (#0)
> GET /get_relative_path_static_handler HTTP/1.1
> Host: localhost:8123
> User-Agent: curl/7.47.0
> Accept: */*
> XXX:xxx
>
< HTTP/1.1 200 OK
< Date: Wed, 29 Apr 2020 04:18:31 GMT
< Connection: Keep-Alive
< Content-Type: text/html; charset=UTF-8
< Transfer-Encoding: chunked
< Keep-Alive: timeout=3
< X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"}
<
<html><body>Relative Path File</body></html>
* Connection #0 to host localhost left intact
``` ```
[Original article](https://clickhouse.tech/docs/en/interfaces/http_interface/) <!--hide--> [Original article](https://clickhouse.tech/docs/en/interfaces/http_interface/) <!--hide-->