4. Query Parameters

1. Query Parameters

path 매개변수의 일부가 아닌 다른 함수 매개변수를 선언하면 자동으로 "query" 매개변수로 해석된다.

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는 & 문자로 구분된 URL에서 ? 뒤에 오는 키-값 쌍의 집합이다.

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

예를 들어 위와 같은 URL에서 query 매개변수는 다음과 같다.

1] skip

값이 0으로 되어 있다.

2] limit

값이 10으로 되어 있다.

위의 예제의 query 매개변수는 URL의 일부이므로 당연하게도 문자열이다.
하지만 Python 타입으로 선언하면, 해당 타입으로 변환되고 이에 대해 유효성이 검사된다.

2. Defaults

query 매개변수는 path의 고정된 부분이 아니라 optional일 수 있으며, 기본값 또한 가질 수 있다.
위의 예에서 기본값은 skip=0과 limit=10이다.

따라서 다음과 같은 URL은 서로 같은 의미를 가진다.

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

하지만 다음과 같은 URL은 조금 다르다.

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

위의 URL의 경우, 함수의 매개변수 값은 다음과 같다.

1] skip=20

URL에 설정했기 때문이다.

2] limit=10

기본값이기 때문이다.

3. Optional parameters

같은 방식으로 default를 None으로 설정하여 optional query 매개변수를 선언할 수 있다.

from typing import Optional
from fastapi import FastAPI

app = FastAPI()

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

    return {"item_id": item_id}

위의 예제와 같은 경우 함수 매개변수 q는 optional이며, 기본적으로 None이 된다.

4. Query parameter type conversion

bool 타입을 선언할 수도 있다.

from typing import Optional
from fastapi import FastAPI

app = FastAPI()

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

위의 예제에서 bool 타입의 short 변수에 "참"을 전달하고 싶은 경우 다음과 같이 query 인수를 전달하면 된다.

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

5. Multiple path an query parameters

여러 path 매개변수와 query 매개변수를 순서와 관계없이 동시에 선언할 수 있다.

from typing import Optional
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: Optional[str] = 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

6. Required query parameters

위의 예제처럼 query 매개변수와 같은 non-path 매개변수에 대한 기본값을 선언하는 것은 필수가 아니다.
default를 특정한 값이 아닌 optional로 만들려면 None으로 설정하면 된다.
하지만 optional이 아닌 required로 만들려면 기본값을 선언할 수 없다.

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

위의 예제에서 query 매개변수 needy는 str 타입의 required query 매개변수이다.

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

위와 같이 URL에 required 매개변수 needy를 추가하지 않으면, 다음과 같은 에러를 확인할 수 있을 것이다.

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

needy는 required 매개변수이기 때문에 항상 다음과 같이 URL에 추가해야 한다.

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

다음과 같이 잘 표시되는 것을 볼 수 있다.

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

필요에 따라 일부 매개변수를 required, default, optional로 정의할 수 있다.

from typing import Optional
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: Optional[int] = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}

    return item

위의 예제의 경우 다음과 같이 3개의 query 매개변수가 있다.

1] needy

required

2] skip

default

3] limit

optional

References

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