diff --git a/docs/uk/docs/tutorial/background-tasks.md b/docs/uk/docs/tutorial/background-tasks.md new file mode 100644 index 000000000..912ba8c2a --- /dev/null +++ b/docs/uk/docs/tutorial/background-tasks.md @@ -0,0 +1,85 @@ +# Фонові задачі + +Ви можете створювати фонові задачі, які будуть виконуватися *після* повернення відповіді. + +Це корисно для операцій, які потрібно виконати після обробки запиту, але клієнту не обов’язково чекати завершення цієї операції перед отриманням відповіді. + +Приклади використання: + +* Надсилання email-сповіщень після виконання певної дії: + * Підключення до поштового сервера та надсилання листа може займати кілька секунд. Ви можете відразу повернути відповідь, а email відправити у фоні. +* Обробка даних: + * Наприклад, якщо отримано файл, який потрібно обробити довготривалим процесом, можна повернути відповідь "Accepted" ("Прийнято", HTTP 202) і виконати обробку файлу у фоні. + +## Використання `BackgroundTasks` + +Спочатку імпортуйте `BackgroundTasks` і додайте його як параметр у Вашу *функцію операції шляху* (path operation function) до `BackgroundTasks`: + +{* ../../docs_src/background_tasks/tutorial001.py hl[1,13] *} + +**FastAPI** автоматично створить об'єкт `BackgroundTasks` і передасть його у цей параметр. + + +## Створення функції задачі + +Створіть функцію, яка буде виконувати фонову задачу. + +Це звичайна функція, яка може отримувати параметри. + +Вона може бути асинхронною `async def` або звичайною `def` функцією – **FastAPI** обробить її правильно. + +У нашому випадку функція записує у файл (імітуючи надсилання email). + +І оскільки операція запису не використовує `async` та `await`, ми визначаємо функцію як звичайну `def`: + +{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *} + +## Додавання фонової задачі + +Усередині Вашої *функції обробки шляху*, передайте функцію задачі в об'єкт *background tasks*, використовуючи метод `.add_task()`: + +{* ../../docs_src/background_tasks/tutorial001.py hl[14] *} + +`.add_task()` приймає аргументи: + +* Функція задача, яка буде виконуватися у фоновому режимі (`write_notification`). Зверніть увагу, що передається обʼєкт без дужок. +* Будь-яка послідовність аргументів, які потрібно передати у функцію завдання у відповідному порядку (`email`). +* Будь-які іменовані аргументи, які потрібно передати у функцію задачу (`message="some notification"`). + +## Впровадження залежностей + +Використання `BackgroundTasks` також працює з системою впровадження залежностей. Ви можете оголосити параметр типу `BackgroundTasks` на різних рівнях: у *функції операції шляху*, у залежності (dependable), у під залежності тощо. + +**FastAPI** знає, як діяти в кожному випадку і як повторно використовувати один і той самий об'єкт, щоб усі фонові задачі були об’єднані та виконувалися у фоновому режимі після завершення основного запиту. + +{* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} + +У цьому прикладі повідомлення будуть записані у файл `log.txt` *після* того, як відповідь буде надіслана. + +Якщо у запиті був переданий query-параметр, він буде записаний у лог у фоновій задачі. + +А потім інша фонова задача, яка створюється у *функції операції шляху*, запише повідомлення з використанням path параметра `email`. + +## Технічні деталі + +Клас `BackgroundTasks` походить безпосередньо з `starlette.background`. + +Він імпортується безпосередньо у FastAPI, щоб Ви могли використовувати його з `fastapi` і випадково не імпортували `BackgroundTask` (без s в кінці) з `starlette.background`. + +Якщо використовувати лише `BackgroundTasks` (а не `BackgroundTask`), то його можна передавати як параметр у *функції операції шляху*, і **FastAPI** подбає про все інше, так само як і про використання об'єкта `Request`. + +Також можна використовувати `BackgroundTask` окремо в FastAPI, але для цього Вам доведеться створити об'єкт у коді та повернути Starlette `Response`, включаючи його. + +Детальніше можна почитати в офіційній документації Starlette про фонові задачі . + +## Застереження + +Якщо Вам потрібно виконувати складні фонові обчислення, і при цьому нема потреби запускати їх у тому ж процесі (наприклад, не потрібно спільного доступу до пам’яті чи змінних), можливо, варто скористатися більш потужними інструментами, такими як Celery. + +Такі інструменти зазвичай потребують складнішої конфігурації та менеджера черги повідомлень/завдань, наприклад, RabbitMQ або Redis. Однак вони дозволяють виконувати фонові задачі в кількох процесах і навіть на кількох серверах. + +Якщо ж Вам потрібно отримати доступ до змінних і об’єктів із тієї ж **FastAPI** - програми або виконувати невеликі фонові завдання (наприклад, надсилати сповіщення електронною поштою), достатньо просто використовувати `BackgroundTasks`. + +## Підсумок + +Імпортуйте та використовуйте `BackgroundTasks` як параметр у *функціях операції шляху* та залежностях, щоб додавати фонові задачі.