개요
2024.10.31-[FastAPI] 요청 데이터 접근 - 경로 매개변수에서 FastAPI에서의 경로 매개변수에 접근하는 방법을 알아보았다. 이번 글에서는 쿼리 매개변수를 정의하고 접근하는 방법을 알아본다.
쿼리 매개변수
쿼리는 URL에서 ? 뒤에 나열되는 &로 구분되는 키-값 쌍을 의미하며, HTTP GET 방식으로 통신할 때 사용한다. 예로 들어 아래 URL에서 쿼리 매개변수는 다음과 같다.
http://127.0.0.1:8000/items/?skip=0&limit=10- skip : 0
- limit : 10
FastAPI에서는 경로에 매핑하는 함수를 정의할 때 경로 매개변수가 아니라 다른 매개변수를 함께 선언하면 쿼리 매개변수로 해석된다. URL의 일부이기 때문에 당연히 문자열 데이터이지만, 타입을 지정하면 지정한 타입으로 해석된다.
from fastapi import FastAPI
import json
app = FastAPI()
fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]
@app.get("/items/")
async def read_item(skip: int, limit: int):
return json.dumps(fake_items_db[skip: skip + limit])
데이터 접근은 함수 매개변수에 접근하듯이 처리하면 된다.
추가로 쿼리 매개변수의 값을 제한할 필요가 있다면, 경로 매개변수와 동일하게 Enum을 활용하면 된다.
기본값 지정
쿼리 매개변수에 기본값을 지정하면 URL에 해당 매개변수 값이 포함되지 않았을 때 사용한다.
@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
return json.dumps(fake_items_db[skip: skip + limit])
따라서 아래의 두 경로는 동일하다고 할 수 있다.
http://127.0.0.1:8000/items/?skip=0&limit=10
http://127.0.0.1:8000/items/
선택적 매개변수
기본값을 None으로 설정하면 쿼리 매개변수를 필수값이 아니라 선택적인 값으로 처리할 수 있다. 반대로 말해, 기본값을 지정하지 않은 쿼리 매개변수는 사용자가 필수로 기재해야 한다.
from fastapi import FastAPI
import json
from typing import Union
app = FastAPI()
@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10, q: Union[str, None] = None):
return json.dumps({'skip': skip,
'limit': limit,
'q': q})
참고로 None으로 기본값을 지정하는 것 자체가 매개변수로 선택적으로 만드는 방법이다. Union 부분은 값 파싱 및 디버깅을 위한 부분이다.
경로/쿼리 매개변수 동시 사용
FastAPI는 경로 매개변수와 쿼리 매개변수를 함께 해석할 수 있다. 함수의 매개변수 중, 경로에 포함되어 있는 변수는 경로 매개변수에 해당하고, 그 외의 변수는 쿼리 매개변수로 취급한다.
from fastapi import FastAPI
import json
from typing import Union
app = FastAPI()
@app.get("/items/{skip}")
async def read_item(skip: int = 0, limit: int = 10, q: Union[str, None] = None):
return json.dumps({'skip': skip,
'limit': limit,
'q': q})
참고 문서
https://fastapi.tiangolo.com/ko/tutorial/query-params/