1. 헤더 매개변수란?
HTTP 요청의 헤더는 요청의 메타데이터를 포함하며, 예를 들어 사용자 인증 정보, 콘텐츠 타입, 캐시 제어 등이 포함된다. FastAPI는 이러한 헤더 정보를 쉽게 추출하고 사용할 수 있게 해준다. 헤더 매개변수는 FastAPI의 라우트 함수에서 직접 요청 헤더를 받아올 수 있도록 도와준다.
2. 기본적인 헤더 매개변수 사용법
헤더 정보를 라우트 함수에서 사용하려면 fastapi 모듈의 Header 클래스를 활용한다. Header 클래스를 매개변수로 사용하여 요청 헤더의 값을 추출할 수 있다.
다음 예제는 X-My-Header라는 사용자 정의 헤더를 읽는 방법을 보여준다:
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/get-header/")
def read_header(x_my_header: str | None = Header(None)):
return {"X-My-Header": x_my_header}위 코드에서 x_my_header 매개변수는 X-My-Header 헤더의 값을 읽어온다. 만약 클라이언트가 이 헤더를 포함하지 않으면, 기본값으로 None이 설정된다.
GET /header/get-header
X-My-Header: my-header응답결과
{
"X-My-Header": "my-header"
}3. 헤더 기본값 설정하기
헤더가 요청에 포함되지 않을 때 기본값을 설정할 수 있다. 이를 통해 요청에 필수 헤더가 없어도 기본값을 사용하여 처리할 수 있다.
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/get-header-default/")
def read_header_with_default(x_my_header: str = Header("default_value")):
return {"X-My-Header": x_my_header}이 경우, X-My-Header 헤더가 요청에 포함되지 않으면 "default_value"가 반환된다.
4. 여러 헤더 처리하기
여러 개의 헤더를 동시에 처리해야 할 때는 Header를 여러 번 사용하여 각 헤더를 매개변수로 처리할 수 있다.
from fastapi import FastAPI, Header
app = FastAPI()
@app.get("/get-multiple-headers/")
def read_multiple_headers(
x_my_header1: str | None = Header(None),
x_my_header2: str | None = Header(None)
):
return {"X-My-Header-1": x_my_header1, "X-My-Header-2": x_my_header2}위 예제에서는 X-My-Header-1과 X-My-Header-2라는 두 개의 헤더를 추출하여 반환한다.
5. 헤더의 필수값 설정하기
헤더가 반드시 요청에 포함되어야 하는 경우, FastAPI는 Header의 기본값을 설정하지 않거나 ...을 사용하여 필수 매개변수로 설정할 수 있다.
from fastapi import FastAPI, Header, HTTPException
app = FastAPI()
@app.get("/get-required-header/")
def read_required_header(x_my_header: str = Header(...)):
return {"X-My-Header": x_my_header}이 경우, X-My-Header 헤더가 요청에 포함되지 않으면 FastAPI는 422 Unprocessable Entity 오류를 반환한다.
6. 헤더의 유효성 검사
헤더 값의 유효성을 검사할 수도 있다. 예를 들어, 헤더 값이 특정 형식이나 값을 따라야 할 때 Header와 조건문을 사용하여 검증할 수 있다.
from fastapi import FastAPI, Header, HTTPException
app = FastAPI()
@app.get("/validate-header/")
def validate_header(x_my_header: str | None = Header(None)):
if x_my_header != "expected_value":
raise HTTPException(status_code=400, detail="Invalid header value")
return {"X-My-Header": x_my_header}이 예제에서는 X-My-Header 값이 "expected_value"와 일치하지 않으면 HTTP 400 Bad Request 오류를 반환한다.
7. 헤더를 활용한 실용적인 예
헤더는 다양한 실용적인 용도로 활용될 수 있다. 예를 들어, API 키를 인증 헤더로 처리하거나, 클라이언트의 언어 설정을 가져오는 데 사용할 수 있다.
from fastapi import FastAPI, Header, HTTPException
app = FastAPI()
@app.get("/api-key/")
def api_key_header(api_key: str | None = Header(None)):
if api_key != "my_secret_key":
raise HTTPException(status_code=401, detail="Invalid API Key")
return {"message": "Access granted"}이 코드에서는 api_key 헤더가 "my_secret_key"와 일치하는 경우에만 접근을 허용한다.
