[FastAPI 공식문서] FastAPI - (6) 쿼리 매개변수와 데이터 검증

🏖️ FastAPI에서 쿼리 매개변수 사용하기

1. 쿼리 매개변수란?

: 쿼리는 URL에서 ? 후에 나오고 &으로 구분되는 키-값 쌍의 집합

쿼리 매개변수는 URL 경로의 일부가 아니라 ? 뒤에 오는 키-값 쌍으로 나타납니다. FastAPI는 함수의 인자로 명시된 변수를 자동으로 쿼리 매개변수로 해석합니다.

1.1 기본 예시

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]

• URL 예시: http://127.0.0.1:8000/items/?skip=0&limit=10
• skip과 limit은 쿼리 매개변수로 해석되며, FastAPI는 해당 값을 자동으로 파싱하고 검증합니다.
• 기본값이 설정된 경우: 위 예시에서 skip=0, limit=10이 기본값이므로, 쿼리 매개변수를 제공하지 않으면 기본값이 사용됩니다.
  • URL http://127.0.0.1:8000/items/와 http://127.0.0.1:8000/items/?skip=0&limit=10은 동일한 결과를 반환합니다.

---

2. 선택적 쿼리 매개변수

쿼리 매개변수를 선택적으로 만들고 싶다면 기본값을 None으로 설정합니다. 이는 쿼리 매개변수를 제공하지 않았을 때 기본적으로 None 값을 갖게 됩니다.

2.1 예시

from typing import Union
from fastapi import FastAPI

app = FastAPI()

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

• 여기서 q는 선택적 쿼리 매개변수입니다.
• URL http://127.0.0.1:8000/items/foo?q=bar로 이동하면 {"item_id": "foo", "q": "bar"} 응답을 받습니다.
• q 매개변수를 제공하지 않고 URL을 호출하면, {"item_id": "foo"}라는 응답이 반환됩니다.

---

3. 쿼리 매개변수의 형변환

FastAPI는 다양한 데이터 타입을 지원하며, 자동으로 쿼리 매개변수의 값을 지정한 타입으로 변환합니다. 예를 들어, bool 타입을 사용하면 다양한 형식으로 True나 False 값을 처리할 수 있습니다.

3.1 bool형 쿼리 매개변수 예시

from typing import Union
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Union[str, None] = None, short: bool = False):
    item = {"item_id": item_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

• URL: http://127.0.0.1:8000/items/foo?short=1
• short는 True로 해석되어 긴 설명이 생략됩니다.
• 다음과 같은 다양한 표현도 모두 True로 인식됩니다:
  • http://127.0.0.1:8000/items/foo?short=True
  • http://127.0.0.1:8000/items/foo?short=true
  • http://127.0.0.1:8000/items/foo?short=on
  • http://127.0.0.1:8000/items/foo?short=yes
• 이러한 값이 제공되지 않으면, short는 기본값인 False로 처리됩니다.

---

4. 경로 매개변수와 쿼리 매개변수의 혼합 사용

경로 매개변수와 쿼리 매개변수를 함께 사용할 수 있으며, FastAPI는 자동으로 각 매개변수를 구분하여 처리합니다.

4.1 예시

from typing import Union
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: Union[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

• 경로 매개변수: user_id, item_id
• 쿼리 매개변수: q, short
• URL 예시: http://127.0.0.1:8000/users/1/items/foo?q=search&short=1
  • user_id = 1, item_id = "foo", q = "search", short = True

---

5. 필수 쿼리 매개변수

쿼리 매개변수를 필수로 만들고 싶다면, 기본값을 선언하지 않으면 됩니다. 이 경우, 쿼리 매개변수가 제공되지 않으면 FastAPI는 오류를 반환합니다.

5.1 필수 쿼리 매개변수 예시

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

• URL: http://127.0.0.1:8000/items/foo
  • 오류: needy 쿼리 매개변수가 없으므로 오류가 발생합니다.

{
  "detail": [
    {
      "loc": ["query", "needy"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

• URL: http://127.0.0.1:8000/items/foo?needy=important
  • 응답: {"item_id": "foo", "needy": "important"}

---

6. 필수 및 선택적 쿼리 매개변수 혼합 사용

FastAPI는 필수 매개변수, 기본값을 가진 매개변수, 선택적 매개변수를 동시에 사용할 수 있습니다.

6.1 예시

from typing import Union
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str, needy: str, skip: int = 0, limit: Union[int, None] = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

• 필수 매개변수: needy (쿼리 매개변수)
• 기본값이 있는 매개변수: skip=0
• 선택적 매개변수: limit=None

URL 예시:

• http://127.0.0.1:8000/items/foo?needy=urgent
  • 응답: {"item_id": "foo", "needy": "urgent", "skip": 0, "limit": None}
• http://127.0.0.1:8000/items/foo?needy=urgent&skip=5&limit=10

• 응답: {"item_id": "foo", "needy": "urgent", "skip": 5, "limit": 10}

---

7. 요약

• 쿼리 매개변수: URL에서 ? 뒤에 오는 키-값 쌍으로 정의됩니다. FastAPI는 해당 매개변수를 자동으로 처리합니다.
• 선택적 쿼리 매개변수: 기본값을 None으로 설정해 선택적으로 사용할 수 있습니다.
• 쿼리 매개변수의 형변환: FastAPI는 bool, int 등 다양한 데이터 타입을 자동으로 변환해줍니다.
• 필수 쿼리 매개변수: 기본값이 없는 경우 필수로 처리되며, 제공되지 않으면 오류가 발생합니다.
• 자동 문서화: FastAPI는 쿼리 매개변수를 기반으로 대화형 API 문서를 자동 생성하여 API 사용자가 쉽게 이해하고 사용할 수 있게 합니다.

---