0Pricing
R Academy · Lekcja

Tworzenie endpointów GET i POST

Obsługuj parametry ścieżki, ciągi zapytań i parsowanie treści żądań.

Tworzenie endpointów GET i POST to bezpłatna lekcja R Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej R Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs R Academy zawiera 4 lekcji w sumie.

Czym jest Plumber?

plumber przekształca zwykłe funkcje R w endpointy HTTP API za pomocą specjalnych adnotacji w komentarzach. Należy opatrzyć funkcję adnotacją #* @get /path, a Plumber utworzy trasę GET, która wywoła tę funkcję i zwróci jej wynik w formacie JSON.

Pakiet można zainstalować za pomocą install.packages('plumber').

Pierwszy endpoint GET

Podstawowe API Plumber znajduje się w pliku (np. api.R). Funkcję należy opatrzyć adnotacją #* @get, po której podaje się ścieżkę. Plumber automatycznie serializuje wartość zwracaną przez funkcję do formatu 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)

Parametry ścieżki z podpowiedziami typów

Zmienne segmenty ścieżki osadza się za pomocą składni z nawiasami ostrymi: /users/<id:int>. Plumber analizuje segment i przekazuje go do funkcji jako argument określonego typu. Obsługiwane typy to między innymi int, dbl i 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"}

Parametry zapytania z użyciem #* @param

Parametry zapytania należy dokumentować za pomocą #* @param name Description. Nazwa parametru musi odpowiadać nazwie argumentu funkcji. Plumber automatycznie odczytuje go z parametrów zapytania — nie trzeba analizować ich ręcznie.

# #* 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)
# }

Tworzenie endpointu POST

Adnotacji #* @post /path należy używać w przypadku endpointów, które otrzymują treść żądania. Specjalny argument req zapewnia dostęp do surowego obiektu żądania. Plumber przekazuje go automatycznie, gdy argument funkcji nosi nazwę 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
#   )
# }

Analizowanie treści żądania

req$postBody zawiera surowy ciąg JSON z treści żądania POST. Należy go przeanalizować za pomocą jsonlite::fromJSON(req$postBody), aby uzyskać nazwaną listę R. Przed przetwarzaniem należy zawsze zweryfikować obecność wymaganych pól.

# #* @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
#   )
# }

Kody stanu HTTP z res$status

Argument res, również wstrzykiwany automatycznie przez Plumber, pozwala ustawić kod stanu odpowiedzi HTTP. Należy ustawić go przed zwróceniem wyniku: res$status <- 404L. Typowe kody:

  • 200 — OK (domyślnie)
  • 201 — utworzono
  • 400 — nieprawidłowe żądanie
  • 404 — nie znaleziono
  • 500 — wewnętrzny błąd serwera
# #* @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]]
# }

Zwracanie nazwanych list jako JSON

Plumber serializuje wartości zwracane przez R do formatu JSON za pomocą jsonlite. Nazwane listy stają się obiektami JSON, a nienazwane listy — tablicami JSON. W przypadku ustrukturyzowanych odpowiedzi należy zwracać nazwaną listę.

# 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}]}

Obiekt routera Plumber

Wczytanie opatrzonego adnotacjami pliku R za pomocą plumb('api.R') tworzy obiekt routera Plumber. Wywołanie pr$run(port = 8000) uruchamia serwer. W środowisku produkcyjnym zazwyczaj wywołuje się 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

Obsługa wielu metod HTTP

Pojedyncza ścieżka może obsługiwać wiele metod dzięki napisaniu osobnych funkcji z adnotacjami. Plumber kieruje żądania do właściwej funkcji na podstawie użytej metody 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)
# }

Testowanie endpointów API

Podczas działania serwera można testować endpointy za pomocą curl w terminalu lub httr2 w języku R. httr2 umożliwia pisanie powtarzalnych testów obok kodu 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)

Szybkie sprawdzenie: parametry ścieżki

Jak zadeklarować parametr ścieżki o nazwie id, który Plumber powinien analizować jako liczbę całkowitą?

Podsumowanie endpointów GET i POST

Tworzenie endpointów REST za pomocą Plumber:

  • #* @get /path tworzy trasę GET, a #* @post /path tworzy trasę POST
  • Parametry ścieżki używają składni <name:type> (int, dbl, chr)
  • Parametry zapytania są automatycznie analizowane i przekazywane do pasujących argumentów funkcji
  • Treść żądania POST jest dostępna za pomocą jsonlite::fromJSON(req$postBody)
  • Dla odpowiedzi HTTP innych niż 200 należy ustawić res$status
  • Należy zwracać nazwane listy — są one automatycznie serializowane do obiektów JSON

Często zadawane pytania

Czy lekcja „Tworzenie endpointów GET i POST” jest bezpłatna?

Tak — pełny tekst „Tworzenie endpointów GET i POST” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu R Academy, przejdź na CoddyKit PRO. Kurs R Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Tworzenie endpointów GET i POST”?

Obsługuj parametry ścieżki, ciągi zapytań i parsowanie treści żądań. Ćwiczysz R Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć R Academy?

Nie wymagamy żadnego doświadczenia. R Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Tworzenie endpointów GET i POST”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji R Academy?

Tak. Każda lekcja R Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Wprowadzenie do Plumber i REST
  2. Tworzenie endpointów GET i POST
  3. Uwierzytelnianie i bezpieczeństwo API
  4. Wdrażanie API Plumber na produkcji
← Powrót do R Academy