ClickHouse/docs/fr/interfaces/http.md
Ivan Blinkov d91c97d15d
[docs] replace underscores with hyphens (#10606)
* Replace underscores with hyphens

* remove temporary code

* fix style check

* fix collapse
2020-04-30 21:19:18 +03:00

24 KiB
Raw Blame History

machine_translated machine_translated_rev toc_priority toc_title
true f865c9653f 19 Interface HTTP

Interface HTTP

Linterface HTTP vous permet Dutiliser ClickHouse sur nimporte quelle plate-forme à partir de nimporte quel langage de programmation. Nous lutilisons pour travailler à partir de Java et Perl, ainsi que des scripts shell. Dans dautres départements, Linterface HTTP est utilisée à partir de Perl, Python et Go. Linterface HTTP est plus limitée que linterface native, mais elle a une meilleure compatibilité.

Par défaut, clickhouse-server écoute HTTP sur le port 8123 (cela peut être modifié dans la configuration).

Si vous faites une requête GET / sans Paramètres, elle renvoie le code de réponse 200 et la chaîne définie dans http_server_default_response valeur par défaut “Ok.” (avec un saut de ligne à la fin)

$ curl 'http://localhost:8123/'
Ok.

Utilisez la requête GET /ping dans les scripts de vérification de la santé. Ce gestionnaire revient toujours “Ok.” (avec un saut de ligne à la fin). Disponible à partir de la version 18.12.13.

$ curl 'http://localhost:8123/ping'
Ok.

Envoyer la demande sous forme DURL query paramètre, ou comme un POSTE. Ou envoyer le début de la requête dans l query paramètre, et le reste dans le POST (nous expliquerons plus tard pourquoi cela est nécessaire). La taille de LURL est limitée à 16 Ko, alors gardez cela à lesprit lors de lenvoi de requêtes volumineuses.

En cas de succès, vous recevez le code de réponse 200 et le résultat dans le corps de réponse. Si une erreur se produit, vous recevez le code de réponse 500 et un texte de description de lerreur dans le corps de la réponse.

Lorsque vous utilisez la méthode GET, readonly est définie. En dautres termes, pour les requêtes qui modifient les données, vous ne pouvez utiliser que la méthode POST. Vous pouvez envoyer la requête elle-même dans le corps du message ou dans le paramètre URL.

Exemple:

$ curl 'http://localhost:8123/?query=SELECT%201'
1

$ wget -O- -q 'http://localhost:8123/?query=SELECT 1'
1

$ echo -ne 'GET /?query=SELECT%201 HTTP/1.0\r\n\r\n' | nc localhost 8123
HTTP/1.0 200 OK
Date: Wed, 27 Nov 2019 10:30:18 GMT
Connection: Close
Content-Type: text/tab-separated-values; charset=UTF-8
X-ClickHouse-Server-Display-Name: clickhouse.ru-central1.internal
X-ClickHouse-Query-Id: 5abe861c-239c-467f-b955-8a201abb8b7f
X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"}

1

Comme vous pouvez le voir, curl est un peu gênant en ce sens que les espaces doivent être échappés URL. Bien que wget échappe à tout lui-même, nous ne recommandons pas de lutiliser car il ne fonctionne pas bien sur HTTP 1.1 lors de lutilisation de keep-alive et Transfer-Encoding: chunked.

$ echo 'SELECT 1' | curl 'http://localhost:8123/' --data-binary @-
1

$ echo 'SELECT 1' | curl 'http://localhost:8123/?query=' --data-binary @-
1

$ echo '1' | curl 'http://localhost:8123/?query=SELECT' --data-binary @-
1

Si une partie de la requête est envoyée dans le paramètre et une partie dans la publication, un saut de ligne est inséré entre ces deux parties de données. Exemple (cela ne fonctionnera pas):

$ echo 'ECT 1' | curl 'http://localhost:8123/?query=SEL' --data-binary @-
Code: 59, e.displayText() = DB::Exception: Syntax error: failed at position 0: SEL
ECT 1
, expected One of: SHOW TABLES, SHOW DATABASES, SELECT, INSERT, CREATE, ATTACH, RENAME, DROP, DETACH, USE, SET, OPTIMIZE., e.what() = DB::Exception

Par défaut, les données sont renvoyées au format TabSeparated (pour plus dinformations, voir “Formats” section). Vous utilisez la clause FORMAT de la requête pour demander tout autre format.

$ echo 'SELECT 1 FORMAT Pretty' | curl 'http://localhost:8123/?' --data-binary @-
┏━━━┓
┃ 1 ┃
┡━━━┩
│ 1 │
└───┘

La méthode POST de transmission des données est nécessaire pour les requêtes INSERT. Dans ce cas, vous pouvez écrire le début de la requête dans le paramètre URL et utiliser POST pour transmettre les données à insérer. Les données à insérer pourraient être, par exemple, un vidage séparé par tabulation de MySQL. De cette façon, la requête INSERT remplace LOAD DATA LOCAL INFILE de MySQL.

Exemples: création dune table:

$ echo 'CREATE TABLE t (a UInt8) ENGINE = Memory' | curl 'http://localhost:8123/' --data-binary @-

Utilisation de la requête Dinsertion familière pour linsertion de données:

$ echo 'INSERT INTO t VALUES (1),(2),(3)' | curl 'http://localhost:8123/' --data-binary @-

Les données peuvent être envoyées séparément de la requête:

$ echo '(4),(5),(6)' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20VALUES' --data-binary @-

Vous pouvez spécifier nimporte quel format de données. Le Values le format est le même que ce qui est utilisé lors de Lécriture INSERT dans les valeurs t:

$ echo '(7),(8),(9)' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20FORMAT%20Values' --data-binary @-

Pour insérer des données à partir dun vidage séparé par des tabulations, spécifiez le format correspondant:

$ echo -ne '10\n11\n12\n' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20FORMAT%20TabSeparated' --data-binary @-

La lecture de la table des matières. Les données sont sorties dans un ordre aléatoire en raison dun traitement de requête parallèle:

$ curl 'http://localhost:8123/?query=SELECT%20a%20FROM%20t'
7
8
9
10
11
12
1
2
3
4
5
6

Suppression de la table.

$ echo 'DROP TABLE t' | curl 'http://localhost:8123/' --data-binary @-

Pour les requêtes réussies qui ne renvoient pas de table de données, un corps de réponse vide est renvoyé.

Vous pouvez utiliser le format de compression ClickHouse interne lors de la transmission de données. Les données compressées ont un format non standard, et vous devrez utiliser le spécial clickhouse-compressor programme de travail (il sest installé avec le clickhouse-client paquet). Pour augmenter lefficacité de linsertion de données, vous pouvez désactiver la vérification de la somme de contrôle côté serveur en utilisant http_native_compression_disable_checksumming_on_decompress paramètre.

Si vous avez spécifié compress=1 dans lURL, le serveur compresse les données quil vous envoie. Si vous avez spécifié decompress=1 dans LURL, le serveur décompresse les mêmes données que vous transmettez POST méthode.

Vous pouvez également choisir dutiliser La compression HTTP. Pour envoyer un compressé POST demande, ajouter len-tête de requête Content-Encoding: compression_method. Pour que ClickHouse compresse la réponse, vous devez ajouter Accept-Encoding: compression_method. Supports ClickHouse gzip, br, et deflate méthodes de compression. Pour activer la compression HTTP, vous devez utiliser le ClickHouse enable_http_compression paramètre. Vous pouvez configurer le niveau de compression des données dans le http_zlib_compression_level pour toutes les méthodes de compression.

Vous pouvez lutiliser pour réduire le trafic réseau lors de la transmission dune grande quantité de données, ou pour créer des vidages qui sont immédiatement compressés.

Exemples denvoi de données avec compression:

#Sending data to the server:
$ curl -vsS "http://localhost:8123/?enable_http_compression=1" -d 'SELECT number FROM system.numbers LIMIT 10' -H 'Accept-Encoding: gzip'

#Sending data to the client:
$ echo "SELECT 1" | gzip -c | curl -sS --data-binary @- -H 'Content-Encoding: gzip' 'http://localhost:8123/'

!!! note "Note" Certains clients HTTP peuvent décompresser les données du serveur par défaut (avec gzip et deflate) et vous pouvez obtenir des données décompressées même si vous utilisez les paramètres de compression correctement.

Vous pouvez utiliser l database Paramètre URL pour spécifier la base de données par défaut.

$ echo 'SELECT number FROM numbers LIMIT 10' | curl 'http://localhost:8123/?database=system' --data-binary @-
0
1
2
3
4
5
6
7
8
9

Par défaut, la base de données enregistrée dans les paramètres du serveur est utilisée comme base de données par défaut. Par défaut, cest la base de données appelée default. Alternativement, vous pouvez toujours spécifier la base de données en utilisant un point avant le nom de la table.

Le nom dutilisateur et le mot de passe peuvent être indiqués de lune des trois façons suivantes:

  1. Utilisation de Lauthentification de base HTTP. Exemple:
$ echo 'SELECT 1' | curl 'http://user:password@localhost:8123/' -d @-
  1. Dans le user et password Les paramètres dURL. Exemple:
$ echo 'SELECT 1' | curl 'http://localhost:8123/?user=user&password=password' -d @-
  1. Utiliser X-ClickHouse-User et X-ClickHouse-Key tête. Exemple:
$ echo 'SELECT 1' | curl -H 'X-ClickHouse-User: user' -H 'X-ClickHouse-Key: password' 'http://localhost:8123/' -d @-

Si le nom dutilisateur nest spécifié, le default le nom est utilisé. Si le mot de passe nest spécifié, le mot de passe vide est utilisé. Vous pouvez également utiliser les paramètres DURL pour spécifier des paramètres pour le traitement dune seule requête ou de profils entiers de paramètres. Exemple: http: / / localhost: 8123/?profil = web & max_rows_to_read=1000000000 & query=sélectionner + 1

Pour plus dinformations, voir le Paramètre section.

$ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:8123/?' --data-binary @-
0
1
2
3
4
5
6
7
8
9

Pour plus dinformations sur les autres paramètres, consultez la section “SET”.

De même, vous pouvez utiliser des sessions ClickHouse dans le protocole HTTP. Pour ce faire, vous devez ajouter l session_id GET paramètre à la demande. Vous pouvez utiliser nimporte quelle chaîne comme ID de session. Par défaut, la session est terminée après 60 secondes dinactivité. Pour modifier ce délai dattente, de modifier la default_session_timeout dans la configuration du serveur, ou ajoutez le session_timeout GET paramètre à la demande. Pour vérifier létat de la session, utilisez session_check=1 paramètre. Une seule requête à la fois peut être exécutée dans une seule session.

Vous pouvez recevoir des informations sur le déroulement dune requête en X-ClickHouse-Progress en-têtes de réponse. Pour ce faire, activez send_progress_in_http_headers. Exemple de len-tête de séquence:

X-ClickHouse-Progress: {"read_rows":"2752512","read_bytes":"240570816","total_rows_to_read":"8880128"}
X-ClickHouse-Progress: {"read_rows":"5439488","read_bytes":"482285394","total_rows_to_read":"8880128"}
X-ClickHouse-Progress: {"read_rows":"8783786","read_bytes":"819092887","total_rows_to_read":"8880128"}

Possibles champs den-tête:

  • read_rows — Number of rows read.
  • read_bytes — Volume of data read in bytes.
  • total_rows_to_read — Total number of rows to be read.
  • written_rows — Number of rows written.
  • written_bytes — Volume of data written in bytes.

Les requêtes en cours dexécution ne sarrêtent pas automatiquement si la connexion HTTP est perdue. Lanalyse et le formatage des données sont effectués côté serveur et lutilisation du réseau peut savérer inefficace. Facultatif query_id le paramètre peut être passé comme ID de requête (nimporte quelle chaîne). Pour plus dinformations, consultez la section “Settings, replace_running_query”.

Facultatif quota_key le paramètre peut être passé comme clé de quota (nimporte quelle chaîne). Pour plus dinformations, consultez la section “Quotas”.

Linterface HTTP permet de transmettre des données externes (tables temporaires externes) pour linterrogation. Pour plus dinformations, consultez la section “External data for query processing”.

Tampon De Réponse

Vous pouvez activer la mise en mémoire tampon des réponses côté serveur. Le buffer_size et wait_end_of_query Les paramètres DURL sont fournis à cette fin.

buffer_size détermine le nombre doctets dans le résultat de tampon dans la mémoire du serveur. Si un corps de résultat est supérieur à ce seuil, le tampon est écrit sur le canal HTTP et les données restantes sont envoyées directement au canal HTTP.

Pour vous assurer que la réponse entière est mise en mémoire tampon, définissez wait_end_of_query=1. Dans ce cas, les données ne sont pas stockées dans la mémoire tampon temporaire du serveur de fichiers.

Exemple:

$ curl -sS 'http://localhost:8123/?max_result_bytes=4000000&buffer_size=3000000&wait_end_of_query=1' -d 'SELECT toUInt8(number) FROM system.numbers LIMIT 9000000 FORMAT RowBinary'

Utilisez la mise en mémoire tampon pour éviter les situations où une erreur de traitement de requête sest produite après lenvoi du code de réponse et des en-têtes HTTP au client. Dans cette situation, un message derreur est écrit à la fin du corps de la réponse, et du côté client, lerreur ne peut être détectée quà létape danalyse.

Requêtes Avec paramètres

Vous pouvez créer une requête avec paramètres et transmettre des valeurs des paramètres de la requête HTTP. Pour plus dinformations, voir Requêtes avec des paramètres pour CLI.

Exemple

$ curl -sS "<address>?param_id=2&param_phrase=test" -d "SELECT * FROM table WHERE int_column = {id:UInt8} and string_column = {phrase:String}"

Interface HTTP prédéfinie

ClickHouse prend en charge des requêtes spécifiques via Linterface HTTP. Par exemple, vous pouvez écrire des données dans un tableau comme suit:

$ echo '(4),(5),(6)' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20VALUES' --data-binary @-

ClickHouse prend également en charge LInterface HTTP prédéfinie qui peut vous aider à une intégration plus facile avec des outils tiers tels que Prometheus exportateur.

Exemple:

  • Tout dabord, ajoutez cette section au fichier de configuration du serveur:
<http_handlers>
  <predefine_query_handler>
      <url>/metrics</url>
        <method>GET</method>
        <queries>
            <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>
  </predefine_query_handler>
</http_handlers>
  • Vous pouvez maintenant demander lurl directement pour les données au format Prometheus:
curl -vvv 'http://localhost:8123/metrics'
*   Trying ::1...
* Connected to localhost (::1) port 8123 (#0)
> GET /metrics HTTP/1.1
> Host: localhost:8123
> User-Agent: curl/7.47.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Wed, 27 Nov 2019 08:54:25 GMT
< Connection: Keep-Alive
< Content-Type: text/plain; charset=UTF-8
< X-ClickHouse-Server-Display-Name: i-tl62qd0o
< Transfer-Encoding: chunked
< X-ClickHouse-Query-Id: f39235f6-6ed7-488c-ae07-c7ceafb960f6
< Keep-Alive: timeout=3
< X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"}
<
# HELP "Query" "Number of executing queries"
# TYPE "Query" counter
"Query" 1

# HELP "Merge" "Number of executing background merges"
# TYPE "Merge" counter
"Merge" 0

# HELP "PartMutation" "Number of mutations (ALTER DELETE/UPDATE)"
# TYPE "PartMutation" counter
"PartMutation" 0

# HELP "ReplicatedFetch" "Number of data parts being fetched from replica"
# TYPE "ReplicatedFetch" counter
"ReplicatedFetch" 0

# HELP "ReplicatedSend" "Number of data parts being sent to replicas"
# TYPE "ReplicatedSend" counter
"ReplicatedSend" 0

* Connection #0 to host localhost left intact

Comme vous pouvez le voir dans lexemple, si <http_handlers> est configuré dans la configuration.fichier xml, ClickHouse fera correspondre les requêtes HTTP reçues au type prédéfini dans <http_handlers>, puis ClickHouse exécutera la requête prédéfinie correspondante si la correspondance est réussie.

Maintenant <http_handlers> pouvez configurer <root_handler>, <ping_handler>, <replicas_status_handler>, <dynamic_query_handler> et <no_handler_description> .

root_handler

<root_handler> renvoie le contenu spécifié pour la requête de chemin racine. Le contenu de retour spécifique est configuré par http_server_default_response dans la configuration.XML. si non spécifié, le retour OK.

http_server_default_response nest pas défini et une requête HTTP est envoyée à ClickHouse. Le résultat est comme suit:

<http_handlers>
    <root_handler/>
</http_handlers>
$ curl 'http://localhost:8123'
Ok.

http_server_default_response est défini et une requête HTTP est envoyée à ClickHouse. Le résultat est comme suit:

<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> peut être utilisé pour sonder la santé du serveur clickhouse actuel. Lorsque le serveur HTTP ClickHouse est normal, laccès à ClickHouse via <ping_handler> sera de retour OK..

Exemple:

<http_handlers>
    <ping_handler>/ping</ping_handler>
</http_handlers>
$ curl 'http://localhost:8123/ping'
Ok.

replicas_status_handler

<replicas_status_handler> est utilisé pour détecter létat du nœud de réplica et le retour OK. si le nœud réplique na pas de délai. Sil y a un retard, renvoyez le retard spécifique. La valeur de <replicas_status_handler> prend en charge la personnalisation. Si vous ne spécifiez pas <replicas_status_handler>, ClickHouse réglage par défaut <replicas_status_handler> être / replicas_status.

Exemple:

<http_handlers>
    <replicas_status_handler>/replicas_status</replicas_status_handler>
</http_handlers>

Aucun retard de cas:

$ curl 'http://localhost:8123/replicas_status'
Ok.

Retard de cas:

$ curl 'http://localhost:8123/replicas_status'
db.stats:  Absolute delay: 22. Relative delay: 22.

predefined_query_handler

Vous pouvez configurer <method>, <headers>, <url> et <queries> dans <predefined_query_handler>.

<method> est responsable de la correspondance de la partie méthode de la requête HTTP. <method> entièrement conforme à la définition de méthode dans le protocole HTTP. Cest une option de configuration. Sil nest pas défini dans le fichier de configuration, il ne correspond pas à la partie méthode de la requête HTTP

<url> est responsable de la correspondance de la partie url de la requête HTTP. Il est compatible avec RE2s expressions régulières. Cest une option de configuration. Sil nest pas défini dans le fichier de configuration, il ne correspond pas à la partie url de la requête HTTP

<headers> est responsable de la correspondance de la partie den-tête de la requête HTTP. Il est compatible avec les expressions régulières de RE2. Cest une option de configuration. Sil nest pas défini dans le fichier de configuration, il ne correspond pas à la partie den-tête de la requête HTTP

<queries> la valeur est une requête prédéfinie de <predefined_query_handler>, qui est exécuté par ClickHouse lorsquune requête HTTP est mise en correspondance et que le résultat de la requête est renvoyé. Cest une configuration incontournable.

<predefined_query_handler> prend en charge les paramètres de réglage et les valeurs query_params.

Lexemple suivant définit les valeurs de max_threads et max_alter_threads Paramètres, puis interroge la table système pour vérifier si ces paramètres ont été définis avec succès.

Exemple:

<root_handlers>
    <predefined_query_handler>
        <method>GET</method>
        <headers>
            <XXX>TEST_HEADER_VALUE</XXX>
            <PARAMS_XXX><![CDATA[(?P<name_1>[^/]+)(/(?P<name_2>[^/]+))?]]></PARAMS_XXX>
        </headers>
        <url><![CDATA[/query_param_with_url/\w+/(?P<name_1>[^/]+)(/(?P<name_2>[^/]+))?]]></url>
        <queries>
            <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>
        </queries>
    </predefined_query_handler>
</root_handlers>
$ 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
max_alter_threads   2

!!! note "Note" Dans un <predefined_query_handler>, un <queries> prend en charge un seul <query> dun type dinsertion.

dynamic_query_handler

<dynamic_query_handler> que <predefined_query_handler> augmenter <query_param_name> .

Clickhouse extrait et exécute la valeur correspondant au <query_param_name> valeur dans lurl de la requête HTTP. ClickHouse réglage par défaut <query_param_name> être /query . Cest une option de configuration. Si il ny a pas de définition dans le fichier de configuration, le paramètre nest pas passé.

Pour expérimenter cette fonctionnalité, lexemple définit les valeurs de max_threads et max_alter_threads et demande si les paramètres ont été définis avec succès. La différence est que dans <predefined_query_handler>, la requête est écrite dans le fichier de configuration. Mais dans <dynamic_query_handler>, la requête est écrite sous la forme de param de la requête HTTP.

Exemple:

<root_handlers>
    <dynamic_query_handler>
        <headers>
            <XXX>TEST_HEADER_VALUE_DYNAMIC</XXX>
            <PARAMS_XXX><![CDATA[(?P<param_name_1>[^/]+)(/(?P<param_name_2>[^/]+))?]]></PARAMS_XXX>
        </headers>
        <query_param_name>query_param</query_param_name>
    </dynamic_query_handler>
</root_handlers>
$ 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'
1
2

Article Original