FastAPI 배우기 - Query Parameters

공식 문서를 번역한 내용입니다.

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

쿼리 매개변수 - FastAPI

---

쿼리 매개변수

경로 매개변수의 일부가 아닌 다른 함수 매개변수를 선언할 때, “쿼리” 매개변수로 자동해석한다.

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에서 ? 후에 나오는 & 으로 구분되는 Key=Value 쌍의 집합이다.

예를들면 :

http://127.0.0.1:8000/items/?skip=0&limit=10

쿼리 매개변수는:

• skip : 값 0을 가진다
• limit : 값 10을 가진다

URL의 일부이므로 “당연히” 문자열이다.

하지만 파이썬 타입과 함께 선언할 경우 (위 예에서 int), 해당 타입으로 변환되고 이에 대해 검증한다.

EX ) limit: int = 10 이렇게 선언할 경우 int형으로 자동변환됨.

기본값

쿼리 매개변수는 경로에서 고정된 부분이 아니기 때문에 선택적일 수 있고 기본값을 가질 수 있다.

위 예에서 skip=0과 limit=10은 기본값을 갖고 있다.

그러므로 아래 URL의 값은

http://127.0.0.1:8000/items/

아래처럼 변한다.

http://127.0.0.1:8000/items/?skip=0&limit=10

하지만 아래처럼 이동한 경우 :

http://127.0.0.1:8000/items/?skip=20

함수의 매개변수 값은 아래가 된다.

• skip = 20 : URL에서 정했기 때문에
• limit = 10 : 기본값이기 때문에

선택적 매개변수

같은 방법으로 기본값을 None으로 설정하여 선택적 매개변수를 선언할 수 있다.

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는 선택적이며 기본값으로 None 값이 된다.

 

|확인
FastAPI는 item_id가 경로 매개변수이고 q는 쿼리 매개변수라는 것을 알 정도로 똑똑하다.

 

|참고
FastAPI는 q가 = None이므로 선택적이라는 것을 인지한다.
Union[str, None]에 있는 Union은 FastAPI(FastAPI는 str 부분만 사용한다)가 사용하는게 아니지만,
Union[str, None]은 편집기에게 코드에서 오류를 찾아낼 수 있게 도와준다.

쿼리 매개변수 형변환

bool형으로 선언할 수도 있고, 아래처럼 변환된다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str, q: 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

이 경우, 아래로 이동하면

http://127.0.0.1:8000/items/foo?short=1

또는

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

또는 다른 어떤 변형(대문자, 첫글자만 대문자 등)이더라도 함수는 매개변수 bool형을 가진 short의 값이 True임을 안다. 그렇지 않은 경우 False다.

여러 경로/쿼리 매개변수

여러 경로 매개변수와 쿼리 매개변수를 동시에 선언할 수 있다.

특정 순서로 선언할 필요가 없다.

매개변수들은 이름으로 감지된다.

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

필수 쿼리 매개변수

경로가 아닌 매개변수에 대한 기본값을 선언할 때, 해당 매개변수는 필수적(Required)이지 않다.

특정값을 추가하지 않고 선택적으로 만들기 위해선 기본값을 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

쿼리 매개변수 needy는 str형인 필수 쿼리 매개변수이다.

브라우저에서 아래 URL을 연다면,

<http://127.0.0.1:8000/items/foo-item>

필수 매개변수 needy를 넣지 않았기 때문에 아래와 같은 오류가 생긴다.

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

needy는 필수 매개변수이므로 URL에 반드시 설정해줘야 한다.

<http://127.0.0.1:8000/items/foo-item?needy=sooooneedy>

아래처럼 작동한다

{
    "item_id": "foo-item",
    "needy": "sooooneedy"
}

물론, 일부 매개변수는 필수로, 다른 일부는 기본값을, 또 다른 일부는 선택적으로 선언할 수 있다.

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: int | None = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

이 경우 3가지 쿼리 매개변수가 있다:

• needy, 필수적인 str.
• skip, 기본값이 0인 int.
• limit, 선택적인 int.
• item_id는 str(문자형)으로 입력되어야 하며, 경로 매개변수다

🍳 경로매개변수와 마찬가지로 enum(열거형)을 사용할 수 있다.