docs: publish translated docs in twelve languages and the tool that maintains them (#3280)
This commit is contained in:
parent
14aa889992
commit
52ad0a8876
1 changed files with 89737 additions and 54 deletions
283
i18n/uk/pages/servers/uri-templates.md
Normal file
283
i18n/uk/pages/servers/uri-templates.md
Normal file
|
|
@ -0,0 +1,283 @@
|
|||
---
|
||||
translation:
|
||||
sections: [4a7033e1ed8ad602, 55dcbfff0c6271bf, 101ef9d14bf4ec46, 4b6c4a845438abc7, f98b46bafbee4acd]
|
||||
tool: 1
|
||||
---
|
||||
# URI-шаблони та безпека шляхів {#uri-templates-and-path-safety}
|
||||
|
||||
Це довідник із синтаксису URI-шаблонів, який приймає
|
||||
[`@mcp.resource`](resources.md), і з політики безпеки шляхів,
|
||||
яку SDK застосовує до видобутих значень. Щоб дізнатися, що таке
|
||||
ресурси й коли їх використовувати, почніть зі сторінки
|
||||
**[Ресурси](resources.md)**; ця сторінка передбачає, що ви вже впевнено оголошуєте
|
||||
ресурси й хочете побачити повний набір операторів, параметри безпеки або
|
||||
низькорівневу інтеграцію.
|
||||
|
||||
Синтаксис шаблонів описано в [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570).
|
||||
SDK підтримує підмножину, відібрану для зіставлення вхідних URI запитів
|
||||
`resources/read`, плюс шар безпеки, який відхиляє значення, що вказували б
|
||||
за межі каталогу, який ви збираєтеся обслуговувати. Подробиці
|
||||
протокольного рівня (формати повідомлень, життєвий цикл, пагінація)
|
||||
дивіться в
|
||||
[специфікації ресурсів MCP](https://modelcontextprotocol.io/specification/latest/server/resources).
|
||||
|
||||
## Повний набір операторів {#the-full-operator-set}
|
||||
|
||||
Простий заповнювач `{user_id}` — це той, який представлено на сторінці **[Ресурси](resources.md)**. Є ще чотири
|
||||
форми операторів; ось вони всі на одному сервері, щоб їх можна було
|
||||
порівняти поруч:
|
||||
|
||||
```python title="server.py" hl_lines="16-17 22-23 28-29 34-35 40-41"
|
||||
--8<-- "docs_src/uri_templates/tutorial001.py"
|
||||
```
|
||||
|
||||
Кожен виділений декоратор — це окремий спосіб розібрати URI на частини.
|
||||
Розділи нижче розглядають їх згори донизу.
|
||||
|
||||
### Проста підстановка: `{name}` {#simple-expansion-name}
|
||||
|
||||
`books://{isbn}` — проста, повсякденна форма. Заповнювач відповідає
|
||||
параметру `isbn`, тож клієнт, який читає `books://978-0441172719`, викликає
|
||||
`get_book("978-0441172719")`.
|
||||
|
||||
Простий `{name}` зупиняється на першому `/`. `books://978/extra` не
|
||||
збігається, бо скісна риска після `978` завершує захоплення, а `/extra`
|
||||
лишається зайвим.
|
||||
|
||||
### Перетворення типів {#type-conversion}
|
||||
|
||||
Видобуті значення надходять як рядки, але можна оголосити точніший
|
||||
тип, і SDK перетворить значення. `orders://{order_id}` потрапляє у функцію
|
||||
з параметром `order_id: int`, тож читання `orders://12345` викликає
|
||||
`get_order(12345)`, а не `get_order("12345")`. Обробник виконує над ним
|
||||
арифметику (`order_id + 1`) без приведення типу.
|
||||
|
||||
### Багатосегментні шляхи: `{+name}` {#multi-segment-paths-name}
|
||||
|
||||
Щоб захопити значення, що містить скісні риски, використовуйте `{+name}`. З
|
||||
шаблоном `manuals://{+path}`:
|
||||
|
||||
* `manuals://returns.md` дає `path = "returns.md"`
|
||||
* `manuals://printing/setup.md` дає `path = "printing/setup.md"`
|
||||
|
||||
Беріть `{+name}` щоразу, коли значення ієрархічне: шляхи файлової
|
||||
системи, вкладені ключі об'єктів, URL-шляхи, які ви проксіюєте.
|
||||
|
||||
### Параметри запиту: `{?a,b,c}` {#query-parameters-abc}
|
||||
|
||||
`reviews://{isbn}{?limit,sort}` розміщує `limit` і `sort` після `?`.
|
||||
Шлях визначає, *яку* книжку читати; рядок запиту уточнює, *як* саме.
|
||||
|
||||
Параметри запиту зіставляються поблажливо: порядок не має значення, зайві
|
||||
ігноруються, а пропущені беруться з типових значень функції. Тож
|
||||
`reviews://978-0441172719` використовує `limit=10, sort="newest"`, а
|
||||
`reviews://978-0441172719?sort=top` перевизначає лише `sort`.
|
||||
|
||||
### Сегменти шляху як список: `{/name*}` {#path-segments-as-a-list-name}
|
||||
|
||||
Якщо кожен сегмент шляху потрібен як окремий елемент списку, а не як один
|
||||
рядок зі скісними рисками, використовуйте `{/name*}`. З шаблоном
|
||||
`shelves://browse{/path*}` клієнт, який читає `shelves://browse/fiction/sci-fi`,
|
||||
викликає `browse_shelf(["fiction", "sci-fi"])`.
|
||||
|
||||
### Довідник із шаблонів {#template-reference}
|
||||
|
||||
Найуживаніші шаблони:
|
||||
|
||||
| Шаблон | Приклад вхідних даних | Результат |
|
||||
|--------------|-----------------------|-------------------------|
|
||||
| `{name}` | `alice` | `"alice"` |
|
||||
| `{name}` | `docs/intro.md` | *немає збігу* (зупиняється на `/`) |
|
||||
| `{+path}` | `docs/intro.md` | `"docs/intro.md"` |
|
||||
| `{.ext}` | `.json` | `"json"` |
|
||||
| `{/segment}` | `/v2` | `"v2"` |
|
||||
| `{?key}` | `?key=value` | `"value"` |
|
||||
| `{?a,b}` | `?a=1&b=2` | `"1"`, `"2"` |
|
||||
| `{/path*}` | `/a/b/c` | `["a", "b", "c"]` |
|
||||
|
||||
### Що відхиляє парсер {#what-the-parser-rejects}
|
||||
|
||||
Деякі форми шаблонів виявляються наперед, а не збоять на першому
|
||||
запиті. `@mcp.resource` розбирає шаблон під час виконання декоратора,
|
||||
тож жодна з них ніколи не дістанеться сервера, що працює.
|
||||
|
||||
`UriTemplate.parse()` викидає `InvalidUriTemplate` у таких випадках:
|
||||
|
||||
* **Дві змінні без нічого між ними.** `manuals://{+path}{ext}`
|
||||
відхиляється: під час зіставлення неможливо визначити, де закінчується
|
||||
`path` і починається `ext`. Поставте між ними літерал
|
||||
(`manuals://{+path}/{ext}`) або скористайтеся оператором, який сам
|
||||
дає роздільник. `manuals://{+path}{.ext}` приймається, бо `{.ext}`
|
||||
сам додає `.`.
|
||||
* **Більш ніж одна багатосегментна змінна.** Щонайбільше одна з `{+var}`,
|
||||
`{#var}` або змінна з explode-модифікатором (`{/var*}`, `{.var*}`, `{;var*}`)
|
||||
на шаблон. Дві — за своєю природою неоднозначні: немає обґрунтованого
|
||||
способу вирішити, яка з них поглине зайвий сегмент.
|
||||
* **Звичайні синтаксичні помилки**: незакрита фігурна дужка, двічі
|
||||
використане ім'я змінної або можливість RFC 6570, яку SDK не підтримує,
|
||||
як-от модифікатор префікса `{var:3}` чи explode у параметрах запиту
|
||||
`{?vars*}`.
|
||||
|
||||
Крім того, `@mcp.resource` викидає `ValueError`, коли параметр обробника
|
||||
прив'язаний до змінної запиту в кінцевій групі `{?...}`/`{&...}` шаблону,
|
||||
але не має типового значення в Python. Ці змінні зіставляються поблажливо
|
||||
(клієнт може пропустити будь-яку з них), тож параметр без типового
|
||||
значення проявився б лише як незрозуміла внутрішня помилка на першому
|
||||
запиті, що його пропускає. `reviews://{isbn}{?limit,sort}` на сервері
|
||||
вище — правильно сформована версія: і `limit`, і `sort` мають типові
|
||||
значення.
|
||||
|
||||
## Безпека {#security}
|
||||
|
||||
Параметри шаблону надходять від клієнта. Якщо вони без перевірки
|
||||
потрапляють в операції з файловою системою чи базою даних, значення на
|
||||
кшталт `../../etc/passwd` можуть вказати за межі каталогу, який ви
|
||||
збиралися обслуговувати.
|
||||
|
||||
### Що SDK перевіряє за замовчуванням {#what-the-sdk-checks-by-default}
|
||||
|
||||
Перш ніж запуститься обробник, SDK відхиляє будь-який параметр, що:
|
||||
|
||||
* виходив би за межі початкового каталогу через компоненти `..`
|
||||
* схожий на абсолютний шлях (`/etc/passwd`, `C:\Windows`) або шлях
|
||||
Windows відносно диска (`C:foo`). Значення відносно диска та
|
||||
ідентифікатор із простором імен на кшталт `x:y` як рядки нерозрізненні,
|
||||
тому будь-яке значення «одна літера плюс двокрапка» за замовчуванням
|
||||
відхиляється; звільніть параметр від перевірки, якщо він закономірно
|
||||
отримує такі значення
|
||||
* містить нульовий байт (`\x00`)
|
||||
|
||||
Перевірка на `..` працює з компонентами шляху, а не шукає підрядок.
|
||||
Значення на кшталт `v1.0..v2.0` чи `HEAD~3..HEAD` проходять, бо `..` там
|
||||
не є окремим сегментом шляху.
|
||||
|
||||
Ці перевірки застосовуються до декодованого значення, тож вони ловлять
|
||||
обхід каталогів незалежно від того, як його закодовано в URI (`../etc`,
|
||||
`..%2Fetc`, `%2E%2E/etc`, `..%5Cetc`, `%00` — усе це виявляється).
|
||||
|
||||
!!! check
|
||||
Прочитайте `manuals://../etc/passwd` із сервера вище — і запит буде
|
||||
відхилено одразу: зіставлення шаблонів зупиняється на першій невдачі,
|
||||
тож жоден наступний (потенційно поблажливіший) шаблон не випробовується
|
||||
як запасний. Клієнт бачить ту саму помилку `-32602` «Unknown resource»,
|
||||
що й для URI, який не збігається з жодним шаблоном, а `read_manual`
|
||||
ніколи не запускається.
|
||||
|
||||
### Обробники файлової системи: використовуйте safe_join {#filesystem-handlers-use-safe_join}
|
||||
|
||||
Вбудовані перевірки зупиняють типові випадки, але не можуть знати меж
|
||||
вашої пісочниці. Для доступу до файлової системи використовуйте
|
||||
`safe_join`, щоб розв'язати шлях і впевнитися, що він лишається всередині
|
||||
базового каталогу:
|
||||
|
||||
```python title="server.py" hl_lines="4 14"
|
||||
--8<-- "docs_src/uri_templates/tutorial002.py"
|
||||
```
|
||||
|
||||
`safe_join` ловить виходи через символьні посилання, послідовності `..`
|
||||
і трюки з абсолютними шляхами, які проста перевірка рядка пропустила б.
|
||||
Якщо розв'язаний шлях виходить за межі `DOCS_ROOT`, функція викидає
|
||||
`PathEscapeError`, який дістається клієнта як `ResourceError`.
|
||||
|
||||
### Коли типова поведінка заважає {#when-the-defaults-get-in-the-way}
|
||||
|
||||
Іноді перевірки блокують закономірні значення. Інструмент імпорту
|
||||
каталогу може навмисно отримувати абсолютний шлях, або параметр може бути
|
||||
відносним посиланням на кшталт `../sibling`, яке обробник безпечно
|
||||
тлумачить, не торкаючись файлової системи. Звільніть такий параметр від
|
||||
перевірки або послабте політику для всього сервера:
|
||||
|
||||
```python title="server.py" hl_lines="9 16-19"
|
||||
--8<-- "docs_src/uri_templates/tutorial003.py"
|
||||
```
|
||||
|
||||
* `security=ResourceSecurity(exempt_params={"source"})` на декораторі
|
||||
пропускає перевірки для цього одного параметра цього одного ресурсу.
|
||||
Решта сервера зберігає типову політику.
|
||||
* `resource_security=` у конструкторі `MCPServer` задає типову політику
|
||||
для кожного ресурсу. Тут `relaxed` повністю вимикає перевірку на `..`.
|
||||
|
||||
Налаштовувані перевірки:
|
||||
|
||||
| Налаштування | За замовчуванням | Що робить |
|
||||
|-------------------------|---------|-------------------------------------|
|
||||
| `reject_path_traversal` | `True` | Відхиляє послідовності `..`, що виходять за межі початкового каталогу |
|
||||
| `reject_absolute_paths` | `True` | Відхиляє `/foo`, `C:\foo`, UNC-шляхи та відносний щодо диска `C:foo` (також ловить `x:y`) |
|
||||
| `reject_null_bytes` | `True` | Відхиляє значення, що містять `\x00` |
|
||||
| `exempt_params` | порожньо | Імена параметрів, для яких перевірки пропускаються |
|
||||
|
||||
Ці перевірки — евристичний попередній фільтр; для доступу до файлової
|
||||
системи межею ізоляції лишається `safe_join`.
|
||||
|
||||
!!! tip
|
||||
Якщо обробник не може виконати запит (файл не існує, ідентифікатор
|
||||
невідомий), викиньте виняток. SDK перетворить його на відповідь з
|
||||
помилкою. Про різницю між помилкою протоколу та помилкою інструмента —
|
||||
на сторінці **[Обробка помилок](handling-errors.md)**.
|
||||
|
||||
## Ресурси на низькорівневому Server {#resources-on-the-low-level-server}
|
||||
|
||||
Якщо ви будуєте на низькорівневому `Server` (див. **[Низькорівневий
|
||||
Server](../advanced/low-level-server.md)**), обробники для протокольних методів
|
||||
`resources/list` і `resources/read` реєструються напряму. Декоратора
|
||||
немає; типи протоколу ви повертаєте самі.
|
||||
|
||||
### Статичні ресурси {#static-resources}
|
||||
|
||||
Для фіксованих URI тримайте реєстр і диспетчеризуйте за точним збігом:
|
||||
|
||||
```python title="server.py" hl_lines="17 21 27"
|
||||
--8<-- "docs_src/uri_templates/tutorial004.py"
|
||||
```
|
||||
|
||||
Обробник списку повідомляє клієнтам, що доступно; обробник читання віддає
|
||||
вміст. Спершу перевірте реєстр, далі перейдіть до шаблонів (нижче), якщо
|
||||
вони є, а для всього іншого викидайте виняток.
|
||||
|
||||
### Шаблони {#templates}
|
||||
|
||||
Рушій шаблонів, який використовує `MCPServer`, міститься в
|
||||
`mcp.shared.uri_template` і працює самостійно. Розбір і зіставлення ті
|
||||
самі; маршрутизацію та політику безпеки ви під'єднуєте самі.
|
||||
|
||||
```python title="server.py" hl_lines="13-16 22-25 29 33 45"
|
||||
--8<-- "docs_src/uri_templates/tutorial005.py"
|
||||
```
|
||||
|
||||
У виділених рядках відбуваються три речі:
|
||||
|
||||
* **Розбір один раз, зіставлення на кожен запит.** `UriTemplate.parse()`
|
||||
будує шаблон; `template.match(uri)` повертає видобуті змінні як `dict`
|
||||
або `None`, якщо URI не підходить. Декодування URL відбувається всередині
|
||||
`match()`; декодовані значення повертаються як є, без перевірки безпеки
|
||||
шляхів. Значення виходять рядками: перетворюйте їх самі
|
||||
(`int(matched["id"])`, `Path(matched["path"])`).
|
||||
* **Застосовуйте перевірки безпеки самі.** Перевірки на `..` та абсолютні
|
||||
шляхи, які `MCPServer` виконує за замовчуванням, містяться в
|
||||
`mcp.shared.path_security`. `read_manual_safely` викликає їх, перш ніж
|
||||
торкнутися `MANUALS`. Якщо параметр не є шляхом файлової системи (ISBN,
|
||||
пошуковий запит), пропустіть перевірки для цього значення: політикою ви
|
||||
керуєте в кожному обробнику окремо, а не через об'єкт конфігурації.
|
||||
* **Список шаблонів із того самого джерела.** Клієнти дізнаються про
|
||||
шаблони через `resources/templates/list`. `str(template)` повертає
|
||||
початковий рядок шаблону, тож список і зіставлювач мають одне джерело
|
||||
істини.
|
||||
|
||||
## Підсумки {#recap}
|
||||
|
||||
* `{name}` збігається з одним сегментом; `{+name}` зберігає скісні риски;
|
||||
`{?a,b}` бере значення з рядка запиту; `{/name*}` розбиває сегменти на
|
||||
список.
|
||||
* Дві змінні без нічого між ними або друга багатосегментна змінна
|
||||
відхиляються під час розбору. Параметр, прив'язаний до змінної запиту в
|
||||
кінцевій групі `{?...}`/`{&...}`, мусить оголошувати типове значення в
|
||||
Python.
|
||||
* Анотуйте параметр (`order_id: int`) — і SDK перетворить значення.
|
||||
* Типова політика безпеки відхиляє `..`, абсолютні шляхи та нульові
|
||||
байти, перш ніж запуститься обробник; перевизначайте для окремого
|
||||
ресурсу через `security=ResourceSecurity(...)` або для всього сервера
|
||||
через `resource_security=`.
|
||||
* Для доступу до файлової системи межею ізоляції є `safe_join`.
|
||||
* На низькорівневому `Server` розбирайте через `UriTemplate.parse()`,
|
||||
зіставляйте через `.match()` і застосовуйте `mcp.shared.path_security`
|
||||
самі.
|
||||
Loading…
Reference in a new issue