WeniVooks

검색

FastAPI 베이스캠프

쿼리 매개변수 처리

1. 라우팅 및 세팅

1.1 URL 정보

이번 챕터의 URL 구성은 아래와 같습니다.

경로 함수명 메서드 설명 쿼리 매개변수
/ index GET 들어온 값을 그대로 출력합니다. -
/item item_list GET 물품 목록을 반환합니다. skip, limit
1.1.1 쿼리 매개변수
  • /item에서 사용할 수 있는 쿼리 매개변수는 아래와 같습니다.
매개변수 타입 필수 여부 설명 기본값
skip integer 선택 건너뛸 아이템 수 0
limit integer 선택 반환할 최대 아이템 수 10
1.1.2 예시
  • /item?skip=0&limit=10: 처음부터 10개의 아이템을 반환
  • /item?skip=10&limit=5: 11번째 아이템부터 5개의 아이템을 반환

이러한 skip과 limit 매개변수를 사용하여 게시판 하단에 페이지를 넘기는 페이지네이션을 구현할 수 있습니다. 이를 통해 게시판 등을 구현할 수 있습니다.

1.2 기본 세팅

이번 실습 폴더는 02_4_query입니다. VSC 터미널에서 사용할 명령어 입니다. 가상환경은 벗어난 상태에서 실행해야 합니다. 만약 터미널 입력창 앞에 (venv)라고 되어 있다면 deactivate 명령어로 가상환경을 나간 상태에서 cd ..으로 상위 폴더로 나와 아래 명령어를 실행해주세요.

mkdir 02_4_query
cd 02_4_query
python -m venv venv
.\venv\Scripts\activate
pip install fastapi
pip install uvicorn
mkdir 02_4_query
cd 02_4_query
python -m venv venv
.\venv\Scripts\activate
pip install fastapi
pip install uvicorn

2. 쿼리 스트링

URL의 구조는 아래와 같습니다.

https://nodejs.org/api/url.html#url

여기서 쿼리 스트링은 ? 뒤에 오는 key=value 형태의 문자열입니다. 쿼리 스트링은 URL의 일부로, 서버에 전달되는 데이터를 담고 있습니다. 쿼리 스트링은 key=value 형태로 &로 연결하여 여러 개의 값을 전달할 수 있습니다. 예를 들어, http://example.com/items?skip=0&limit=10에서 skip=0과 limit=10이 쿼리 매개변수입니다.

3. 선택적 쿼리 매개변수

선택적 쿼리 매개변수는 사용자가 제공하지 않아도 되는 매개변수입니다. FastAPI에서는 이를 기본값을 설정하거나 Optional을 사용하여 구현할 수 있습니다.

from fastapi import FastAPI
from typing import Optional
 
app = FastAPI()
 
 
@app.get("/items")
async def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}
from fastapi import FastAPI
from typing import Optional
 
app = FastAPI()
 
 
@app.get("/items")
async def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

이 예제에서 skip과 limit은 선택적 쿼리 매개변수입니다. 사용자가 값을 제공하지 않으면 기본값이 사용됩니다.

아래 URL을 통해 이 함수에 접근할 수 있습니다.

  • http://127.0.0.1:8000/items: 기본값인 skip=0과 limit=10이 사용됩니다.
  • http://127.0.0.1:8000/items?skip=5: skip=5와 기본값인 limit=10이 사용됩니다.
  • http://127.0.0.1:8000/items?skip=5&limit=20: skip=5와 limit=20이 사용됩니다.

skip과 limit의 이름을 변경하거나 기본값을 변경 또는 타입힌트를 변경하여 어떤 값이 출력되는지 확인해보세요.

from fastapi import FastAPI
from typing import Optional
 
app = FastAPI()
 
 
@app.get("/items")
async def read_items(hello: str = "world", limit: int = 10):
    return {"hello": hello, "limit": limit}
from fastapi import FastAPI
from typing import Optional
 
app = FastAPI()
 
 
@app.get("/items")
async def read_items(hello: str = "world", limit: int = 10):
    return {"hello": hello, "limit": limit}

3. 필수 쿼리 매개변수

필수 쿼리 매개변수는 사용자가 반드시 제공해야 하는 매개변수입니다. FastAPI에서는 기본값을 설정하지 않음으로써 필수 매개변수를 정의할 수 있습니다.

from fastapi import FastAPI
 
app = FastAPI()
 
 
@app.get("/items")
async def read_items(item_id: int):
    return {"item_id": item_id}
from fastapi import FastAPI
 
app = FastAPI()
 
 
@app.get("/items")
async def read_items(item_id: int):
    return {"item_id": item_id}

이 예제에서 item_id는 필수 쿼리 매개변수입니다. 사용자가 이 값을 제공하지 않으면 FastAPI는 자동으로 오류를 반환합니다.

아래 URL을 통해 이 함수에 접근할 수 있습니다.

  • http://127.0.0.1:8000/items?item_id=5: item_id=5를 제공하면 {"item_id": 5}가 반환됩니다.
  • http://127.0.0.1:8000/items: item_id를 제공하지 않으면 오류가 발생합니다.

4. 여러 쿼리 매개변수 사용하기

여러 개의 쿼리 매개변수를 동시에 사용할 수 있습니다. 선택적 매개변수와 필수 매개변수를 조합하여 사용할 수 있습니다.

from fastapi import FastAPI
 
app = FastAPI()
 
 
@app.get("/items")
async def read_items(item_id: int, q: str | None = None):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results
from fastapi import FastAPI
 
app = FastAPI()
 
 
@app.get("/items")
async def read_items(item_id: int, q: str | None = None):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

이 예제에서 item_id는 필수 매개변수이고, q는 선택적 매개변수입니다.

5. 타입 변환 및 검증

FastAPI는 쿼리 매개변수의 타입을 자동으로 변환하고 검증합니다. 예를 들어, int로 선언된 매개변수에 문자열이 입력되면 FastAPI는 자동으로 정수로 변환을 시도하고, 실패하면 오류를 반환합니다.

from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/items")
async def read_items(item_id: int, price: float):
    return {"item_id": item_id, "price": price}
from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/items")
async def read_items(item_id: int, price: float):
    return {"item_id": item_id, "price": price}

이 예제에서 item_id는 정수로, price는 부동소수점 숫자로 자동 변환됩니다.

6. 불리언 타입 쿼리 매개변수

불리언 타입의 쿼리 매개변수도 사용할 수 있습니다. FastAPI는 다양한 형태의 불리언 값을 인식합니다.

from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/items")
async def read_items(item_id: int, is_available: bool = True):
    return {"item_id": item_id, "is_available": is_available}
from fastapi import FastAPI
 
app = FastAPI()
 
@app.get("/items")
async def read_items(item_id: int, is_available: bool = True):
    return {"item_id": item_id, "is_available": is_available}

이 엔드포인트는 http://example.com/items?item_id=123&is_available=true 또는 http://example.com/items?item_id=123&is_available=1과 같은 URL을 처리할 수 있습니다.

연습문제

  1. 상품 목록 리스트를 만들어서 페이지네이션을 구현해보세요. 이 API는 다음과 같은 쿼리 매개변수를 받아야 합니다.

    items = [
    {"name": "item1", "price": 1000, "available": True},
    {"name": "item2", "price": 2000, "available": False},
    {"name": "item3", "price": 3000, "available": True},
    {"name": "item4", "price": 4000, "available": False},
    {"name": "item5", "price": 5000, "available": True},
    {"name": "item6", "price": 6000, "available": False},
    {"name": "item7", "price": 7000, "available": True},
    {"name": "item8", "price": 8000, "available": False},
    {"name": "item9", "price": 9000, "available": True},
    {"name": "item10", "price": 10000, "available": False},
]
    items = [
    {"name": "item1", "price": 1000, "available": True},
    {"name": "item2", "price": 2000, "available": False},
    {"name": "item3", "price": 3000, "available": True},
    {"name": "item4", "price": 4000, "available": False},
    {"name": "item5", "price": 5000, "available": True},
    {"name": "item6", "price": 6000, "available": False},
    {"name": "item7", "price": 7000, "available": True},
    {"name": "item8", "price": 8000, "available": False},
    {"name": "item9", "price": 9000, "available": True},
    {"name": "item10", "price": 10000, "available": False},
]
    • page (선택): 페이지 번호 (정수, 기본값 1)
    • size (선택): 페이지당 상품 수 (정수, 기본값 10)

  2. 상품 검색 API를 만들어보세요. 이 API는 다음과 같은 쿼리 매개변수를 받아야 합니다.

    • name (선택): 상품 이름으로 검색 (문자열)
    • min_price (선택): 최소 가격 (숫자)
    • max_price (선택): 최대 가격 (숫자)
    • available (선택): 재고 여부 (불리언)

  3. 사용자 목록을 반환하는 API를 만들어보세요. 이 API는 다음과 같은 쿼리 매개변수를 받아야 합니다.

    • page (선택): 페이지 번호 (정수, 기본값 1)
    • size (선택): 페이지당 사용자 수 (정수, 기본값 10)
    • sort_by (선택): 정렬 기준 ('name' 또는 'age', 기본값 'name')
2.3 요청 본문 처리2.5 응답 모델 사용하기