[파이썬] FastAPI - 쿼리 매개변수, 경로 매개변수, 백그라운드 태스크

이전 내용

[파이썬] FastAPI - 정적 파일, API Router

---

쿼리 매개변수와 경로 매개변수

 

FastAPI는 API를 통해 데이터를 요청할 때 주로 쿼리 매개변수와 경로 매개변수 두 가지를 사용한다.

• 쿼리 매개변수: URL의 ? 이후에 위치하며, 주로 선택적인 데이터를 전달하기 위해 사용된다. 여러 개의 매개변수를 &, 즉 ampersand로 구분하여 전달할 수 있다.
• 경로 매개변수: URL 경로의 일부로 설정되며, 필수적인 데이터를 전달할 때 사용된다. 경로 매개변수는 중괄호 {}로 감싸서 지정한다.

---

쿼리 매개변수

 

URL에서 ? 기호 뒤에 위치하는 키와 값의 쌍을 쿼리 매개변수 또는 쿼리 파라미터라고 한다. 이러한 쿼리 매개변수를 사용한 한 URL 내에서 다양한 데이터를 서버로 전송하고, 서버는 이를 해석하여 요청에 따라 다른 결과를 반환할 수 있다.

 

[FastAPI에서 쿼리 매개변수를 처리하는 방법]

함수의 인자로 쿼리 매개변수의 이름을 추가하기만 하면 FastAPI가 이를 자동으로 인식하고 해당 URL로부터 값들을 추출하여 함수에 전달한다.

 

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    return {"skip":skip, "limit":limit}

• 함수가 호출될 때 FastAPI는 'skip'과 'limit' 매개변수에 대한 값을 요청 URL에서 추출하여 전달한다.
• 사용자가 값을 명시하지 않을 시에는 기본값 설정도 가능하다.

이제 서버를 실행하고, skip에는 5, limit에는 6의 값을 주는 링크로 접속하면

http://127.0.0.1:8000/items/?skip=5&limit=6

JSON 형태로 값을 반환한다.

---

경로 매개변수

 

경로 매개변수는 URL의 특정 부분을 동적으로 만들어주는 요소로, 일정한 패턴의 URL을 동적으로 처리할 수 있게 해준다.

예를 들어, 사용자의 ID에 따라 다른 정보를 보여주고 싶을 때 경로 매개변수를 사용할 수 있다.

 

FastAPI에서 경로 매개변수를 사용하려면 중괄호 {}를 사용하며, 중괄호 안에 들어가는 이름이 파이썬 함수의 매개변수 이름과 일치해야 한다.

• 기본 형태: {parameter}
• 타입지정: {parameter: type} ▶ 예. {item_id: int}
• 경로 매개변수 연산자: {parameter: path}

FastAPI에서는 타입 힌트를 사용하여 경로 매개변수의 타입을 지정하며, 이렇게 하면 FastAPI가 자동으로 검증을 해준다.

예를 들어, /items/{item_id:int} 에서 item_id 는 정수여야 한다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_items(item_id):
    return {"item_id": item_id}

---

타입 지정과 경로 매개변수 연산자

 

◆ 타입 지정

타입을 명시적으로 지정하면 FastAPI는 그 타입에 따라 값의 유효성을 검증한다.

타입 지정은 경로 매개변수에서만, 또는 함수에서만 타입 지정을 해도 유사한 기능을 확인할 수 있다.

from fastapi import FastAPI

app = FastAPI()

# 타입 지정1
@app.get("/items/{item_id: int}")
async def read_items(item_id):
    return {"item_id": item_id}
    
# 타입 지정2
@app.get("/items/{item_id}")
async def read_items(item_id:int):
    return {"item_id": item_id}

 

만약, items/ 뒤에 정수가 아닌 값이 오게 되면 에러가 발생하게 된다.

◆ 경로 매개변수 연산자

경로 매개변수 연산자 :path를 사용하면 슬래시(/)를 포함한 문자열도 캡처할 수 있다.

from fastapi import FastAPI

@app.get("/files/{sub_path:path}")
async def read_files(sub_path:str):
    return {"sub_path": sub_path}

---

백그라운드 태스크

 

FastAPI의 백그라운드 태스크(Background Tasks)는 비동기적으로 처리해야 할 작업을 엔드포인트 요청 처리 과정 외부에서 수행할 수 있도록 도와주는 기능이다. 이를 통해 서버는 응답을 클라이언트에게 빠르게 반환하면서, 시간이 걸리는 작업을 별도로 처리할 수 있다. 주로 이메일 전송, 데이터 처리, 로그 기록 등과 같은 작업에 유용하게 사용된다.

 

주로 긴 작업을 별도로 처리하는 데 사용하며, 이는 HTTP 응답을 먼저 보내고 나서도 서버에서 계속 작업을 실행할 수 있게 해준다.이를 통해 서버 리소스를 효율적으로 활용할 수 있다.

 

예. 사용자가 회원 가입 시, 회원 가입 환영 메일을 보내는 작업은 시간이 걸릴 수 있기 때문에, 이 작업을 별도의 배경 작업으로 처리하고, 사용자에게는 즉시 응답을 보낼 수 있다.

1. 백그라운드 태스크의 정의

• 비동기 처리: 사용자가 요청한 작업이 완료될 때까지 기다리지 않고, 즉시 응답을 반환한 후에 작업이 실행된다.
• 리소스 최적화: 주요 로직과 무관한 작업을 분리하여 리소스를 효율적으로 사용할 수 있다.
• 성능 향상: 서버의 응답 속도를 높이고 사용자 경험을 향상시킬 수 있다.

2. 사용법

• FastAPI에서는 BackgroundTasks 클래스를 사용하여 백그라운드 태스크를 쉽게 정의하고 사용할 수 있다.

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def write_log(message:str):
    with open("log.txt", "a") as log:
        log.write(message)

@app.get("/")
async def read_root(background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, "root endpoint was accessed")
    return {"message": "Welcome to My Page"}

• BackgroundTasks: FastAPI의 내장 클래스로, 이를 통해 별도의 스레드에서 실행될 작업들을 관리하고 예약할 수 있다. 이 클래스는 FastAPI 애플리케이션에서 다양한 백그라운드 태스크를 쉽게 다룰 수 있도록 설계되었으며, 특히 I/O 작업이나 시간이 오래 걸리는 작업에 유용하다.
• add_task(): BackgroundTasks 클래스의 메소드. 이 메소드를 사용하면 실행할 함수와 그 함수에 전달할 매개변수를 지정할 수 있다. 매개변수는 위치 기반 또는 키워드 기반으로 전달한다.

background_tasks.add_taks(func, *args, **kwargs)

• func: 실행할 함수
• *args: 함수에 전달할 위치 기반 매개변수
• **kwargs: 함수에 전달할 키워드 기반 매개변수

정상적으로 실행됐을 경우, main.py 파일이 실행된 폴더에 log.txt 파일이 생성되고 안에 내용(로그)이 작성되어있다.

 

1. 특징

• 비동기 방식: 백그라운드 태스크는 비동기 방식으로 구현하여, 주 애플리케이션과는 별개로 실행된다.
• 상태 유지: 백그라운드 태스크는 서버의 상태를 유지할 수 있도록 접근할 수 있으며, 필요에 따라 데이터베이스 연결을 사용할 수 있다.
• 리소스 관리: 요청의 응답 시간이 길어지지 않도록 할 수 있으며, 시스템 자원을 효율적으로 사용할 수 있도록 도와준다.

2. 유용한 패턴

• 시간 소모 작업: 이메일 전송, 정기적인 데이터 업데이트, 처리해야 할 긴 계산작업 등이 적합하다.
• 로깅: 사용자의 행위나 애플리케이션의 상태를 기록하는 경우 로깅 작업을 백그라운드에서 처리할 수 있다.

3. 주의사항

• 백그라운드 태스크 실행 순서: 백그라운드 태스크는 요청을 처리한 후에 실행되며, 응답이 클라이언트에게 반환된 후에 작동하므로, 태스크의 우선순위나 실행 시간은 예측하기 어려울 수 있다.
• 자원 관리: 많은 태스크를 동시에 실행할 경우, 서버의 메모리와 CPU 자원을 고갈시킬 위험이 있으므로, 적절한 리소스 관리를 계획해야 한다.

 

◆ add_task() 메소드의 다양한 방식

 

1. 기본 함수 추가: 함수만 전달하는 가장 기본적인 형태

background_tasks.add_task(send_email)

2. 인수를 가진 함수 추가: 함수를 등록할 때 필요한 인수를 함께 전달하여, 백그라운드에서 해당 인수를 바탕으로 작업 수행

background_tasks.add_task(send_email, email="example@example.com", message="Hello!")

3. 비동기 함수 추가: 비동기 함수를 백그라운드 태스크로 추가하여, 비동기적인 처리가 필요한 상황에서도 사용 가능

background_tasks.add_task(async_function)

4. 고차 함수 추가 (선택적 인수의 경우): 함수를 등록할 때 람다 표현식을 사용하여, 특정 인수가 필요할 경우 이를 동적으로 처리하는 방법

background_tasks.add_task(lambda: some_function(optional_arg="value"))

5. 여러 태스크 등록: 여러 개의 태스크를 순차적으로 등록하여, 각각의 작업이 백그라운드에서 독립적으로 실행

background_tasks.add_task(send_email, "to1@example.com", "Message 1")
background_tasks.add_task(send_email, "to2@example.com", "Message 2")

---

[참고]

가장 빠른 풀스택을 위한 플라스크 & FastAPI

---

다음 내용

[파이썬] FastAPI - 스트리밍 응답