Создание конечных точек GET и POST
Обрабатывайте параметры пути, строки запроса и разбор тела запроса
«Создание конечных точек GET и POST» — бесплатный урок R Academy на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения R Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс R Academy содержит 4 уроков всего.
Что такое Plumber
plumber превращает обычные функции R в конечные точки HTTP API с помощью специальных аннотаций в комментариях. Добавьте к функции аннотацию #* @get /path, и Plumber создаст маршрут GET, который вызовет эту функцию и вернет ее результат в формате JSON.
Установите пакет с помощью install.packages('plumber').
Ваша первая конечная точка GET
Простой API Plumber хранится в файле (например, api.R). Добавьте к функции аннотацию #* @get, а затем укажите путь. Plumber автоматически сериализует возвращаемое функцией значение в JSON.
# api.R
# library(plumber)
#
# #* Return a greeting
# #* @get /hello
# function() {
# list(message = 'Hello from Plumber!')
# }
#
# Start with:
# pr <- plumb('api.R')
# pr$run(port = 8000)Параметры пути с подсказками типов
Встраивайте переменные сегменты пути с помощью синтаксиса угловых скобок: /users/<id:int>. Plumber разбирает сегмент и передает его функции как аргумент указанного типа. Поддерживаются типы int, dbl и chr.
# #* Get a user by ID
# #* @get /users/<id:int>
# function(id) {
# # id is already an integer
# list(
# user_id = id,
# name = paste('User', id)
# )
# }
#
# GET /users/42 => {"user_id":42, "name":"User 42"}Параметры запроса с помощью #* @param
Документируйте параметры запроса с помощью #* @param name Description. Имя параметра должно совпадать с именем аргумента функции. Plumber автоматически считывает его из строки запроса — вручную разбирать ее не нужно.
# #* Search users by name
# #* @param name The name to search for
# #* @param limit Maximum results to return
# #* @get /users/search
# function(name = '', limit = '10') {
# limit <- as.integer(limit)
# # query string: /users/search?name=Alice&limit=5
# list(query = name, max = limit)
# }Создание конечной точки POST
Используйте #* @post /path для конечных точек, принимающих тело запроса. Специальный аргумент req предоставляет доступ к исходному объекту запроса. Plumber передает его автоматически, если аргумент функции называется req.
# #* Create a new user
# #* @post /users
# function(req) {
# body <- jsonlite::fromJSON(req$postBody)
# # body$name, body$email are now available
# list(
# status = 'created',
# user_id = sample(1000:9999, 1),
# name = body$name
# )
# }Разбор тела запроса
req$postBody содержит исходную строку JSON из тела POST-запроса. Разберите ее с помощью jsonlite::fromJSON(req$postBody), чтобы получить именованный список R. Перед обработкой всегда проверяйте наличие обязательных полей.
# #* @post /orders
# function(req, res) {
# body <- jsonlite::fromJSON(req$postBody)
# if (is.null(body$product_id)) {
# res$status <- 400L
# return(list(error = 'product_id is required'))
# }
# list(
# order_id = as.integer(Sys.time()),
# product_id = body$product_id,
# quantity = body$quantity %||% 1
# )
# }Коды состояния HTTP с res$status
Аргумент res (который Plumber также внедряет автоматически) позволяет задать код состояния ответа HTTP. Установите его перед возвратом значения: res$status <- 404L. Распространенные коды:
- 200 — OK (по умолчанию)
- 201 — создано
- 400 — неверный запрос
- 404 — не найдено
- 500 — внутренняя ошибка сервера
# #* @get /items/<id:int>
# function(id, res) {
# items <- list(
# list(id=1, name='Widget'),
# list(id=2, name='Gadget')
# )
# found <- Filter(function(x) x$id == id, items)
# if (length(found) == 0) {
# res$status <- 404L
# return(list(error = paste('Item', id, 'not found')))
# }
# found[[1]]
# }Возврат именованных списков в формате JSON
Plumber сериализует возвращаемые значения R в JSON с помощью jsonlite. Именованные списки становятся объектами JSON, а безымянные — массивами JSON. Для структурированных ответов возвращайте именованный список.
# Named list => JSON object
# list(id=1, name='Alice') => {"id":1, "name":"Alice"}
#
# Unnamed list => JSON array
# list(1, 2, 3) => [1, 2, 3]
#
# Nested structures work too:
# list(
# user = list(id=1, name='Alice'),
# orders = list(list(id=101), list(id=102))
# )
# => {"user":{"id":1,"name":"Alice"}, "orders":[{"id":101},{"id":102}]}Объект маршрутизатора Plumber
Загрузите аннотированный файл R с помощью plumb('api.R'), чтобы создать объект маршрутизатора Plumber. Вызовите pr$run(port = 8000), чтобы запустить сервер. В рабочей среде обычно вызывают pr_run(pr, host='0.0.0.0', port=8000).
# Standard plumber startup in api_start.R:
# library(plumber)
# pr <- plumb('api.R')
# pr$run(port = 8000, host = '0.0.0.0')
#
# Or with pipe style:
# plumb('api.R') |> pr_run(port = 8000)
#
# Test with:
# curl http://localhost:8000/helloОбработка нескольких HTTP-методов
Один путь может поддерживать несколько методов, если написать отдельные функции с аннотациями. Plumber направляет запрос к правильной функции в зависимости от использованного HTTP-метода.
# #* List all products
# #* @get /products
# function() {
# list(products = list(list(id=1, name='Widget')))
# }
#
# #* Create a product
# #* @post /products
# function(req) {
# body <- jsonlite::fromJSON(req$postBody)
# list(created = TRUE, name = body$name)
# }Тестирование конечных точек API
Используйте curl в терминале или httr2 из R, чтобы проверять конечные точки во время работы сервера. httr2 позволяет писать воспроизводимые тесты рядом с кодом API.
# From terminal:
# curl http://localhost:8000/users/42
# curl -X POST http://localhost:8000/users \
# -H 'Content-Type: application/json' \
# -d '{"name":"Alice","email":"alice@example.com"}'
#
# From R:
# library(httr2)
# resp <- request('http://localhost:8000/users/42') |> req_perform()
# resp_body_json(resp)Быстрая проверка: параметры пути
Как объявить параметр пути с именем id, который Plumber должен разобрать как целое число?
Итоги по конечным точкам GET и POST
Создание конечных точек REST с помощью Plumber:
#* @get /pathсоздаёт маршрут GET;#* @post /pathсоздаёт маршрут POST- Параметры пути используют синтаксис
<name:type>(int,dbl,chr) - Параметры запроса автоматически разбираются и передаются в аргументы функций с соответствующими именами
- Тело POST доступно через
jsonlite::fromJSON(req$postBody) - Устанавливайте
res$statusдля HTTP-ответов с кодом, отличным от 200 - Возвращайте именованные списки — они автоматически преобразуются в объекты JSON
Часто задаваемые вопросы
Урок «Создание конечных точек GET и POST» бесплатный?
Да — полный текст урока «Создание конечных точек GET и POST» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс R Academy, подпишись на CoddyKit PRO. Курс R Academy содержит 4 уроков всего.
Чему я научусь в уроке «Создание конечных точек GET и POST»?
Обрабатывайте параметры пути, строки запроса и разбор тела запроса Ты практикуешь R Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать R Academy?
Предыдущий опыт не требуется. R Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.
Сколько времени занимает урок «Создание конечных точек GET и POST»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке R Academy?
Да. Каждый урок R Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Введение в Plumber и REST
- Создание конечных точек GET и POST
- Аутентификация и безопасность API
- Развёртывание API Plumber в рабочей среде