[FastAPI] 3. 쿼리 매개변수(Query Parameters)

쿼리 매개변수

from fastapi import FastAPI

app = FastAPI()

fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

• 경로 매개변수에 포함되어 있지 않은 매개 변수들은 자동으로 쿼리 매개변수(query parameter)로 인식
  • 이 예시에서는 skip, limit이 query parameter
• 쿼리는 URL의 ? 뒤에 오는 키-값 쌍 집합을 의미하고 각각의 변수들은 &로 구분
  • ex) http://127.0.0.1:8000/items/?skip=0&limit=1
  • skip 변수의 값 0, limit 변수의 값 1
• 기본적으로 url의 일부이기에 string으로 해석됨
• Python type을 이용해서 선언해놓으면 해당 타입으로 변환되어 검증 가능
  • 여기서는 skip: int = 0, limit: int = 10. int 형으로 선언해서 위의 예시 url의 경우 skip의 값으로 "0"이 아니라 int형 0으로, limit의 경우 "1"이 아니라 int형 1로 자동 변환되어 값이 들어감
• 함수 선언시 skip: int = 0, limit: int = 10으로 default값을 설정할 수 있음
  • ex) http://127.0.0.1:8000/items/?skip=20
  • 이 예시에서는 skip은 20이고 limit은 따로 값을 지정하지 않았으므로 default값인 10이 됨

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

• Query parameter를 필수가 아니라 선택적으로 설정하기 위해서는 default 값을 None으로 설정
  • ex) q: str | None = None (파이썬 3.10 이상 버전)
  • str | None:  str 타입의 변수이잔, 기본값이 None일 수 있음을 나타냄
  • = None: 해당 매개변수의 기본값이 None임을 지정
• 기본값이  None이면 함수 호출시 해당 변수를 생략할 수 있고, 그런 경우 그 변수는 None 값을 가짐

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_user_item(item_id: str, needy: str):
    item = {"item_id": item_id, "needy": needy}
    return item

• 기본값을 설정하지 않으면 required query parameter가 되어서 값이 입력되지 않으면 Field required error가 발생

 

여러 경로 매개변수와 쿼리 매개변수 선언

• 여러 개의 경로 매개변수와 쿼리 매개변수를 동시에 선언 가능
• 매개변수의 이름을 기준을 path parameter와 query parameter 구분하기에 선언 순서에 구애받지 않음

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(
    user_id: int, item_id: str, q: str | None = None, short: bool = False
):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

https://fastapi.tiangolo.com/tutorial/query-params/

Query Parameters - FastAPI