[ FastAPI ] 쿼리 매개변수

만약 경로 매개변수의 일부가 아닌 다른 함수 매개변수를 선언한다면, 그것들은 자동으로 "쿼리" 매개변수로 해석됩니다.

 

 

쿼리는 & 문자로 구분되고, URL 속 ? 다음에 오는 키-값 쌍으로 이루어진 집합입니다.

 

예를 들어, 다음과 같은 URL이 있습니다:

 

 

... 여기서 쿼리 매개변수는 다음과 같습니다:

 

• skip : 0 이라는 값을 가집니다.
• limit : 10 이라는 값을 가집니다.

 

이것들은 URL의 한 부분이기 때문에, "당연히" 문자열입니다.

 

그러나 (위 예시에서의 int 처럼) 파이썬 자료형으로 선언한다면 이것은 해당 자료형으로 변환되고 유효성 검사가 진행됩니다.

 

경로 매개변수에서 동작하는 모든 작업은 쿼리 매개변수에서도 동작합니다:

 

• (명백한) 편집기의 지원
• 데이터 "파싱"
• 데이터 유효성 검사
• 자동 문서

 

기본 값

쿼리 매개변수가 경로에 고정된 부분이 아니라면, 그것은 선택 사항이 되어 기본 값을 가질 수 있습니다.

 

위 예시에서는 skip=0 과 limit=10 이라는 기본 값을 갖게 됩니다.

 

이제, 다음 URL에 접속해보시기 바랍니다:

 

 

이것은 다음에 접속하는 것과 동일합니다:

 

 

그러나 다음과 같은 예시에 접속한다면:

 

 

당신의 함수 속 매개변수의 값은 다음과 같습니다:

 

• skip=20 : URL에 값을 입력했기 때문입니다
• limit=10 : 기본 값이기 때문입니다

 

선택적 매개변수

같은 방식으로, None 을 기본 값으로 가지는, 선택적 쿼리 매개변수를 선언할 수 있습니다:

 

 

이 경우, 함수의 매개변수 q 는 선택 사항이 되고 기본 값으로 None 이 됩니다.

 

확인
FastAPI는 경로 매개변수 item_id 를 경로 매개변수로 인지하지만 q 는 아니기 때문에, 쿼리 매개변수로 인지할 만큼 똑똑합니다.

 

참고
FastAPI는 =None 때문에 q 가 선택사항이라는 걸 압니다.

Optional[str] 속 Optional 은 FastAPI에 의해 사용되지 않지만 (FastAPI는 str 부분만 사용합니다), Optional[str] 는 편집기가 코드 속 오류를 찾는 데 도와줍니다.

 

쿼리 매개변수의 자료형 변환

물론 bool 자료형을 선언할 수도 있고, 이것은 변환됩니다:

 

 

이 경우, 만약 다음과 같은 곳에 접속한다면:

 

 

또는

 

 

또는

 

 

또는

 

 

또는

 

 

또는 다른 다양한 예시 속에서 (대문자, 첫 글자만 대문자, 기타 등등), 당신의 함수는 매개변수 short 를 True 값인 bool 로 인식합니다. 아닌 경우는 False 로 인식합니다.

 

다중 경로와 쿼리 매개변수

다중 경로 매개변수와 쿼리 매개변수를 동시에 선언할 수 있으며, FastAPI는 각각을 구분할 수 있습니다.

 

그리고 어떤 특정 순서를 가지고 선언할 필요는 없습니다.

 

그것들은 이름에 의해 탐지되기 때문입니다:

 

 

요구되는 쿼리 매개변수

만약 당신이 비-경로 매개변수의 기본 값을 선언한다면 (지금까지, 우리는 쿼리 매개변수만 살펴봤습니다), 이것은 요구되지 않습니다.

 

만약 특별한 값을 추가하길 원하지 않고 단지 선택사항으로 만들고 싶다면, 기본 값을 None 으로 설정하시기 바랍니다.

 

그러나 만약 쿼리 매개변수를 반드시 요구하게 만들고 싶다면, 어떤 기본 값도 정의하지만 않으면 됩니다:

 

 

여기 쿼리 매개변수 needy 는 str 자료형의 반드시 요구되는 쿼리 매개변수입니다.

 

만약 브라우저에서 다음과 같은 URL에 접속한다면:

 

 

... 그리고 요구되는 needy 매개변수를 추가하지 않는다면, 다음과 같은 에러를 볼 수 있습니다:

 

 

needy 는 요구되는 매개변수이기 때문에, URL에 다음과 같은 입력이 필요합니다:

 

 

... 이것은 다음과 같이 동작합니다:

 

 

그리고 당연하게도, 어떤 매개변수는 요구되게, 어떤 매개변수는 기본 값을 가지게, 그리고 어떤 매개변수는 완전히 선택사항으로 정의할 수 있습니다:

 

 

이 경우, 3개의 쿼리 매개변수가 있습니다:

 

• str 을 요구하는, needy .
• 기본 값으로 0 을 가지는 int , skip .
• 선택적 int , limit .

 

팁
경로 매개변수 와 같은 방법으로 Enum 을 사용할 수 있습니다.

 

---

원문

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

Query Parameters - FastAPI