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