Mercurial > hg > nginx-site

comparison xml/ru/docs/njs/njs_api.xml @ 2182:7865ca0da0ab

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merged HTTP request,response, and reply in njs.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 19 Jun 2018 15:43:42 +0300
parents cd4889fdcfa4
children 23cfb62121d1
comparison
equal deleted inserted replaced
2181:b73ccabb852b 2182:7865ca0da0ab
21 </section> 21 </section>
22 22
23 23
24 <section id="http" name="HTTP"> 24 <section id="http" name="HTTP">
25 25
26
27 <section id="http_request" name="Запрос">
28
26 <para> 29 <para>
27 Объекты <literal>HTTP</literal> доступны только в 30 Объекты <literal>HTTP</literal> доступны только в
28 модуле <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link>. 31 модуле <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link>.
29 </para> 32 </para>
30 33
31
32 <section id="http_request" name="Запрос">
33
34 <para> 34 <para>
35 <list type="tag"> 35 <list type="tag">
36 36
37 <tag-name><literal>req.uri</literal></tag-name> 37 <tag-name><literal>r.args{}</literal></tag-name>
38 <tag-desc> 38 <tag-desc>
39 текущий URI запроса, только чтение 39 объект аргументов запроса, только чтение
40 </tag-desc> 40 </tag-desc>
41 41
42 <tag-name><literal>req.method</literal></tag-name> 42 <tag-name><literal>r.error(<value>строка</value>)</literal></tag-name>
43 <tag-desc> 43 <tag-desc>
44 метод запроса, только чтение 44 записывает <literal>строку</literal> в лог-файл ошибок
45 </tag-desc> 45 на уровне лога <literal>error</literal>
46 46 </tag-desc>
47 <tag-name><literal>req.httpVersion</literal></tag-name> 47
48 <tag-desc> 48 <tag-name><literal>r.finish()</literal></tag-name>
49 версия HTTP, только чтение 49 <tag-desc>
50 </tag-desc> 50 завершает отправку ответа клиенту
51 51 </tag-desc>
52 <tag-name><literal>req.remoteAddress</literal></tag-name> 52
53 <tag-desc> 53 <tag-name><literal>r.headersIn{}</literal></tag-name>
54 адрес клиента, только чтение 54 <tag-desc>
55 </tag-desc> 55 объект исходящих заголовков, только чтение.
56
57 <tag-name><literal>req.headers{}</literal></tag-name>
58 <tag-desc>
59 объект заголовков запроса, только чтение.
60 <para> 56 <para>
61 Например, доступ к заголовку <literal>Header-Name</literal> 57 Например, доступ к заголовку <literal>Header-Name</literal>
62 можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal> 58 можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal>
63 или <literal>headers.Header_name</literal> 59 или <literal>headers.Header_name</literal>
64 </para> 60 </para>
65 </tag-desc> 61 </tag-desc>
66 62
67 <tag-name><literal>req.args{}</literal></tag-name> 63 <tag-name><literal>r.headersOut{}</literal></tag-name>
68 <tag-desc> 64 <tag-desc>
69 объект аргументов запроса, только чтение 65 объект исходящих заголовков, доступно для записи.
70 </tag-desc> 66 <para>
71 67 Например, доступ к заголовку <literal>Header-Name</literal>
72 <tag-name><literal>req.variables{}</literal></tag-name> 68 можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal>
73 <tag-desc> 69 или <literal>headers.Header_name</literal>
74 объект переменных nginx, только чтение 70 </para>
75 </tag-desc> 71 </tag-desc>
76 72
77 <tag-name><literal>req.response</literal></tag-name> 73 <tag-name><literal>r.httpVersion</literal></tag-name>
78 <tag-desc> 74 <tag-desc>
79 объект <link id="http_response_object">ответа</link> (0.2.0), только чтение 75 версия HTTP, только чтение
80 </tag-desc> 76 </tag-desc>
81 77
82 <tag-name><literal>req.log(<value>строка</value>)</literal></tag-name> 78 <tag-name><literal>r.log(<value>строка</value>)</literal></tag-name>
83 <tag-desc> 79 <tag-desc>
84 записывает <literal>строку</literal> в лог-файл ошибок 80 записывает <literal>строку</literal> в лог-файл ошибок
85 на уровне лога <literal>info</literal> 81 на уровне лога <literal>info</literal>
86 </tag-desc> 82 </tag-desc>
87 83
88 <tag-name><literal>req.warn(<value>строка</value>)</literal></tag-name> 84 <tag-name><literal>r.method</literal></tag-name>
85 <tag-desc>
86 HTTP метод, только чтение
87 </tag-desc>
88
89 <tag-name><literal>r.parent</literal></tag-name>
90 <tag-desc>
91 ссылается на родительский объект запроса
92 </tag-desc>
93
94 <tag-name><literal>r.remoteAddress</literal></tag-name>
95 <tag-desc>
96 адрес клиента, только чтение
97 </tag-desc>
98
99 <tag-name><literal>r.requestBody</literal></tag-name>
100 <tag-desc>
101 хранит тело запроса, только чтение
102 </tag-desc>
103
104 <tag-name><literal>r.responseBody</literal></tag-name>
105 <tag-desc>
106 хранит тело ответа <link id="subrequest">подзапроса</link>, только чтение
107 </tag-desc>
108
109 <tag-name><literal>r.return(код[, строка])</literal></tag-name>
110 <tag-desc>
111 отправляет
112 клиенту полный ответ с указанным <literal>кодом</literal>
113 <para>
114 Можно задать или URL перенаправления
115 (для кодов 301, 302, 303, 307 и 308),
116 или текст тела ответа (для остальных кодов) в качестве второго аргумента
117 </para>
118 </tag-desc>
119
120 <tag-name><literal>r.send(<value>строка</value>)</literal></tag-name>
121 <tag-desc>
122 отправляет часть тела ответа клиенту
123 </tag-desc>
124
125 <tag-name><literal>r.sendHeader()</literal></tag-name>
126 <tag-desc>
127 отправляет заголовок HTTP клиенту
128 </tag-desc>
129
130 <tag-name><literal>r.status</literal></tag-name>
131 <tag-desc>
132 статус, доступно для записи
133 </tag-desc>
134
135 <tag-name><literal>req.variables{}</literal></tag-name>
136 <tag-desc>
137 объект переменных nginx, только чтение
138 </tag-desc>
139
140 <tag-name><literal>r.warn(<value>строка</value>)</literal></tag-name>
89 <tag-desc> 141 <tag-desc>
90 записывает <literal>строку</literal> в лог-файл ошибок 142 записывает <literal>строку</literal> в лог-файл ошибок
91 на уровне лога <literal>warning</literal> (0.2.0) 143 на уровне лога <literal>warning</literal>
92 </tag-desc> 144 </tag-desc>
93 145
94 <tag-name><literal>req.error(<value>строка</value>)</literal></tag-name> 146 <tag-name><literal>r.uri</literal></tag-name>
95 <tag-desc> 147 <tag-desc>
96 записывает <literal>строку</literal> в лог-файл ошибок 148 текущий URI, только чтение
97 на уровне лога <literal>error</literal> (0.2.0) 149 </tag-desc>
98 </tag-desc> 150
99 151 <tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[,
100 <tag-name id="subrequest"><literal>req.subrequest(<value>uri</value>[,
101 <value>options</value>[, <value>callback</value>]])</literal></tag-name> 152 <value>options</value>[, <value>callback</value>]])</literal></tag-name>
102 <tag-desc> 153 <tag-desc>
103 создаёт подзапрос с заданными <literal>uri</literal> и 154 создаёт подзапрос с заданными <literal>uri</literal> и
104 <literal>options</literal> и 155 <literal>options</literal> и
105 устанавливает необязательный <literal>callback</literal> завершения (0.2.0). 156 устанавливает необязательный <literal>callback</literal> завершения.
106 157
107 <para> 158 <para>
108 Если <literal>options</literal> является строкой, то в ней 159 Если <literal>options</literal> является строкой, то в ней
109 содержится срока аргументов подзапроса. 160 содержится срока аргументов подзапроса.
110 В противном случае ожидается, что <literal>options</literal> является объектом 161 В противном случае ожидается, что <literal>options</literal> является объектом
111 со следующими ключами: 162 со следующими ключами:
163
112 <list type="tag"> 164 <list type="tag">
113 <tag-name><literal>args</literal></tag-name> 165 <tag-name><literal>args</literal></tag-name>
114 <tag-desc> 166 <tag-desc>
115 строка с аргументами 167 строка с аргументами
116 </tag-desc> 168 </tag-desc>
127 179
128 </list> 180 </list>
129 </para> 181 </para>
130 182
131 <para> 183 <para>
132 <literal>callback</literal> 184 <literal>callback</literal> получает
133 получает объект <link id="http_reply">reply</link>. 185 объект ответа подзапроса с методами и свойствами,
134 </para> 186 идентичными родительскому объекту запроса.
135 </tag-desc> 187 </para>
136
137 </list>
138 </para>
139
140 </section>
141
142
143 <section id="http_response" name="Ответ">
144
145 <para>
146 <list type="tag">
147
148 <tag-name><literal>res.status</literal></tag-name>
149 <tag-desc>
150 статус ответа, доступно для записи
151 </tag-desc>
152
153 <tag-name><literal>res.headers{}</literal></tag-name>
154 <tag-desc>
155 объект заголовков ответа
156 </tag-desc>
157
158 <tag-name><literal>res.contentType</literal></tag-name>
159 <tag-desc>
160 значение поля <header>Content-Type</header> заголовка ответа,
161 доступно для записи
162 </tag-desc>
163
164 <tag-name><literal>res.contentLength</literal></tag-name>
165 <tag-desc>
166 значение поля <header>Content-Length</header> заголовка ответа,
167 доступно для записи
168 </tag-desc>
169
170 <tag-name><literal>res.sendHeader()</literal></tag-name>
171 <tag-desc>
172 отправляет заголовок HTTP клиенту
173 </tag-desc>
174
175 <tag-name><literal>res.send(<value>строка</value>)</literal></tag-name>
176 <tag-desc>
177 отправляет часть тела ответа клиенту
178 </tag-desc>
179
180 <tag-name><literal>res.finish()</literal></tag-name>
181 <tag-desc>
182 завершает отправку ответа клиенту
183 </tag-desc>
184
185 <tag-name><literal>res.return(код[, строка])</literal></tag-name>
186 <tag-desc>
187 отправляет
188 клиенту полный ответ с указанным <literal>кодом</literal> (0.2.0)
189 <para>
190 Можно задать или URL перенаправления
191 (для кодов 301, 302, 303, 307 и 308),
192 или текст тела ответа (для остальных кодов) в качестве второго аргумента
193 </para>
194 </tag-desc>
195
196 </list>
197 </para>
198
199 </section>
200
201
202 <section id="http_reply" name="Reply">
203
204 <para>
205 <list type="tag">
206
207 <tag-name><literal>reply.uri</literal></tag-name>
208 <tag-desc>
209 текущий URI, только чтение
210 </tag-desc>
211
212 <tag-name><literal>reply.method</literal></tag-name>
213 <tag-desc>
214 метод, только чтение
215 </tag-desc>
216
217 <tag-name><literal>reply.status</literal></tag-name>
218 <tag-desc>
219 статус, доступно для записи
220 </tag-desc>
221
222 <tag-name><literal>reply.contentType</literal></tag-name>
223 <tag-desc>
224 значение поля <header>Content-Type</header> заголовка,
225 доступно для записи
226 </tag-desc>
227
228 <tag-name><literal>reply.contentLength</literal></tag-name>
229 <tag-desc>
230 значение поля <header>Content-Length</header> заголовка,
231 доступно для записи
232 </tag-desc>
233
234 <tag-name><literal>reply.headers{}</literal></tag-name>
235 <tag-desc>
236 объект заголовков ответа, только чтение
237 </tag-desc>
238
239 </list>
240 </para>
241
242 <para>
243 Кроме того, у объект <literal>reply</literal> имеет
244 следующие свойства:
245
246 <list type="tag">
247
248 <tag-name><literal>reply.body</literal></tag-name>
249 <tag-desc>
250 хранит тело ответа подзапроса
251 </tag-desc>
252
253 <tag-name><literal>reply.parent</literal></tag-name>
254 <tag-desc>
255 ссылается на родительский объект запроса
256 </tag-desc> 188 </tag-desc>
257 189
258 </list> 190 </list>
259 </para> 191 </para>
260 192
338 </tag-desc> 270 </tag-desc>
339 271
340 <tag-name><literal>s.warn(<value>строка</value>)</literal></tag-name> 272 <tag-name><literal>s.warn(<value>строка</value>)</literal></tag-name>
341 <tag-desc> 273 <tag-desc>
342 записывает отправленную <literal>строку</literal> в лог-файл ошибок 274 записывает отправленную <literal>строку</literal> в лог-файл ошибок
343 на уровне лога <literal>warning</literal> (0.2.0) 275 на уровне лога <literal>warning</literal>
344 </tag-desc> 276 </tag-desc>
345 277
346 <tag-name><literal>s.error(<value>строка</value>)</literal></tag-name> 278 <tag-name><literal>s.error(<value>строка</value>)</literal></tag-name>
347 <tag-desc> 279 <tag-desc>
348 записывает отправленную <literal>строку</literal> в лог-файл ошибок 280 записывает отправленную <literal>строку</literal> в лог-файл ошибок
349 на уровне лога <literal>error</literal> (0.2.0) 281 на уровне лога <literal>error</literal>
350 </tag-desc> 282 </tag-desc>
351 283
352 </list> 284 </list>
353 </para> 285 </para>
354 286
355 </section> 287 </section>
356 288
357 </section> 289 </section>
358 290
359 291
292 <section id="example" name="Примеры">
293
294
295 <section id="example_urldecode" name="Декодирование URL">
296
297 <para>
298 <example>
299 js_include urldecode.js;
300
301 js_set $decoded_foo decoded_foo;
302 </example>
303 </para>
304
305 <para>
306 Файл <path>urldecode.js</path>:
307 <example>
308 function decoded_foo(r) {
309 return decodeURIComponent(r.args.foo);
310 }
311 </example>
312 </para>
313
314 </section>
315
316
317 <section id="example_urlencode" name="Кодирование URL">
318
319 <para>
320 <example>
321 js_include urlencode.js;
322
323 js_set $encoded_foo encoded_foo;
324 ...
325
326 location / {
327 proxy_pass http://example.com?foo=$encoded_foo;
328 }
329 </example>
330 </para>
331
332 <para>
333 Файл <path>urlencode.js</path>:
334 <example>
335 function encoded_foo(r) {
336 return encodeURIComponent('foo &amp; bar?');
337 }
338 </example>
339 </para>
340
341 </section>
342
343
344 <section id="example_fast_response" name="Возврат самого быстрого ответа от прокси">
345
346 <para>
347 <example>
348 js_include fastresponse.js;
349
350 location /start {
351 js_content content;
352 }
353
354 location /foo {
355 proxy_pass http://backend1;
356 }
357
358 location /bar {
359 proxy_pass http://backend2;
360 }
361 </example>
362 </para>
363
364 <para>
365 Файл <path>fastresponse.js</path>:
366 <example>
367 function content(r) {
368 var n = 0;
369
370 function done(res) {
371 if (n++ == 0) {
372 r.return(res.status, res.responseBody);
373 }
374 }
375
376 r.subrequest('/foo', r.variables.args, done);
377 r.subrequest('/bar', r.variables.args, done);TBD
378 }
379 </example>
380 </para>
381
382 </section>
383
384
385 <section id="example_jwt" name="Создание HS JWT">
386
387 <para>
388 <example>
389 js_include hs_jwt.js;
390
391 js_set $jwt jwt;
392 </example>
393 </para>
394
395 <para>
396 Файл <path>hs_jwt.js</path>:
397 <example>
398 function create_hs256_jwt(claims, key, valid) {
399 var header = { "typ" : "JWT", "alg" : "HS256", "exp" : Date.now() + valid };
400
401 var s = JSON.stringify(header).toBytes().toString('base64url') + '.'
402 + JSON.stringify(claims).toBytes().toString('base64url');
403
404 var h = require('crypto').createHmac('sha256', key);
405
406 return s + '.' + h.update(s).digest().toString('base64url');
407 }
408
409 function jwt(r) {
410 var claims = {
411 "iss" : "nginx",
412 "sub" : "alice",
413 "foo" : 123,
414 "bar" : "qq",
415 "zyx" : false
416 };
417
418 return create_hs256_jwt(claims, 'foo', 600);
419 }
420 </example>
421 </para>
422
423 </section>
424
425
426 <section id="example_subrequest" name="Доступ к API при помощи подзапроса">
427
428 <para>
429 <example>
430 js_include subrequest.js;
431
432 keyval_zone zone=foo:10m;
433 ...
434
435 location /keyval {
436 js_content set_keyval;
437 }
438
439 location /version {
440 js_content version;
441 }
442
443 location /api {
444 api write=on;
445 }
446 </example>
447 </para>
448
449 <para>
450 Файл <path>subrequest.js</path>:
451 <example>
452 function set_keyval(r) {
453 r.subrequest('/api/3/http/keyvals/foo',
454 { method: 'POST',
455 body: JSON.stringify({ foo: 789, bar: "ss dd 00" })},
456
457 function(res) {
458 if (res.status >= 300) {
459 r.return(res.status, res.responseBody);
460 return;
461 }
462 r.return(500);
463 });
464 }
465 function version(r) {
466 r.subrequest('/api/3/nginx', { method: 'GET' }, function(res) {
467 if (res.status != 200) {
468 r.return(res.status);
469 return;
470 }
471
472 var json = JSON.parse(res.responseBody);
473 r.return(200, json.version);
474 });
475 }
476 </example>
477 </para>
478
479 </section>
480
481
482 <section id="example_secure_link" name="Создание хэша secure_link">
483
484 <para>
485 <example>
486 js_include hash.js;
487
488 js_set $new_foo create_secure_link;
489 ...
490
491 location / {
492 secure_link $cookie_foo;
493 secure_link_md5 "$uri mykey";
494 ...
495 }
496
497 location @login {
498 add_header Set-Cookie "foo=$new_foo; Max-Age=60";
499 return 302 /;
500 }
501 </example>
502 </para>
503
504 <para>
505 Файл <path>hash.js</path>:
506 <example>
507 function create_secure_link(r) {
508 return require('crypto').createHash('md5')
509 .update(r.uri).update(" mykey")
510 .digest('base64url');
511 }
512 </example>
513 </para>
514
515 </section>
516
517 </section>
518
360 </article> 519 </article>
361 520