[ FastAPI ] 요청 파일

https://github.com/swagger-api/swagger-ui/issues/4276

File 을 사용하여 클라이언트에 의해 업로드될 파일을 정의할 수 있습니다.

 

정보

업로드된 파일을 전달 받을 때, 우선 python-multipart 를 설치해야 합니다.

예를 들어 pip install python-mutipart 와 같은 방식으로 가능합니다.

왜냐하면 "폼 데이터"로 업로드된 파일이 전송되어지기 때문입니다.

 

임포트 File

fastapi 로부터 File 및 UploadFile 을 임포트합니다:

 

 

File 매개변수 정의

Body 또는 Form 과 동일한 방법으로 파일 매개변수를 만듭니다:

 

 

정보

File 은 Form 을 직접 상속 받는 클래스입니다.

그러나 Query , Path , File 그리고 기타 등등을 fastapi 로부터 임포트할 때, 이것들은 실제로 특별한 클래스를 반환하는 함수라는 사실을 기억하기 바랍니다.

 

팁

파일 바디를 선언하기 위해서는, 매개변수를 쿼리 매개변수 또는 바디 (JSON) 매개변수로 해석하기 때문에, 반드시 File 을 사용해야 합니다.

 

파일은 "폼 데이터"로 업로드 됩니다.

 

만약 경로 동작 함수 매개변수의 자료형을 bytes 로 선언한다면, FastAPI는 파일을 조회하고 bytes 로 콘텐츠를 전달 받습니다.

 

모든 콘텐츠가 메모리에 저장되는 걸 명심하시기 바랍니다. 따라서 작은 파일을 다룰 때 잘 작동합니다.

 

그러나 UploadFile 을 사용해서 장점을 얻을 수 있는 사례가 몇 가지 있습니다.

 

UploadFile을 사용한 File 매개변수

UploadFile 자료형을 사용하여 File 파라미터를 정의합니다.

 

 

UploadFile 을 사용하면 bytes 에 비해 여러 장점이 있습니다:

 

• "스풀링된" 파일을 사용합니다:
  • 파일은 최대 크기 제한까지 메모리에 저장되며, 이후 해당 제한을 넘어서면 디스크에 저장됩니다.
• 이것은 이미지, 비디오, 대용량 바이너리, 기타 등등의 대용량 파일들이 모든 메모리를 소비하지 않고 잘 작동한다는 걸 의미합니다.
• 업로드된 파일로부터 메타데이터를 얻을 수 있습니다.
• 파일류 객체 aysnc 인터페이스를 갖습니다.
• 파일류 객체를 기대하는 다른 라이브러리에 직접 전달할 수 있는 실제 파이썬 SpooledTemporaryFile 객체를 노출합니다.

 

UploadFile

UploadFile 은 다음과 같은 어트리뷰트를 갖습니다:

 

• filename : ( myimage.jpg 처럼) 업로드된 본래의 파일 이름을 사용한 str .
• content_type : ( image/jpeg 처럼) (MIME 타입 / 미디어 타입) 콘텐츠 유형을 사용한 str .
• file : (파일류 객체인) SpooledTemporaryFile . "파일류" 객체를 기대하는 다른 함수 또는 라이브러리에 직접 전달할 수 있는 실제 파이썬 파일.

 

UploadFile 은 다음과 같은 async 메서드를 갖습니다. 이것들은 모두 (내부 SpooledTemporaryFile 을 사용하여) 밑단에서 해당 파일 메서드를 호출합니다.

 

• write(data) : 파일에 data ( str 또는 bytes ) 작성.
• read(size) : 파일의 size ( int ) 바이트/문자 조회.
• seek(offset) : 파일 속 바이트 위치 offset ( int ) 이동.
  • 예를 들어, await myfile.seek(0) 은 파일의 시작점으로 이동.
  • await myfile.read() 을 단 한 번 실행하고 해당 콘텐츠를 다시 조회할 필요가 있을 때 유용.
• close() : 파일 닫기.

 

이 모든 메서드는 async 메서드이기 때문에, "await"를 사용해야 합니다.

 

예를 들어, aysnc 경로 동작 함수 내부에서 다음과 같이 콘텐츠를 얻을 수 있습니다:

 

 

만약 보통의 def 경로 동작 함수 내부였다면, 아래 예시처럼, UploadFile.file 에 바로 접근할 수 있습니다:

 

 

async 기술적 세부사항

async 메서드를 사용할 때, FastAPI는 스레드풀에서 파일 메서드를 실행하고 이들을 기다립니다.

 

Starlettet 기술적 세부사항

FastAPI는 Starlette의 UploadFile 을 직접 상속 받지만, Pydantic 및 FastAPI의 다른 기능들과 호환될 수 있게 몇 가지 필요한 부분들이 추가됩니다.

 

"폼 데이터"

HTML 폼 ( <form></form> )이 서버에 데이터를 전달하는 방식은 보통, JSON과는 다른 데이터에 "특별한" 부호화를 사용합니다.

 

FastAPI는 JSON 대신 올바른 위치에서 해당 데이터를 조회할 수 있게 합니다.

 

기술적 세부사항

폼으로부터 전달 받은 데이터는 파일을 포함하지 않을 때 보통 "미디어 타입" application/x-www-form-urlencoded 를 사용하여 부호화됩니다.

그러나 폼에 파일이 포함되면, multipart/form-data 로 부호화됩니다. 만약 File 을 사용하면, FastAPI는 바디의 올바른 부분으로부터 파일을 전달 받아야 된다는 것을 알게 됩니다.

만약 이러한 부호화 및 폼 필드에 관해 더 많이 알고 싶다면, POST 와 관련된 MDN 웹 문서를 참고하기 바랍니다.

 

주의

경로 동작 내부에 다중 File 및 Form 매개변수를 선언할 수 있지만, application/json 대신 multipart/form-data 를 사용하여 부호화된 바디가 있기 때문에, JSON으로 전달 받을 것이라 예상되는 Body 필드를 선언할 수는 없습니다.

이것은 FastAPI의 한계가 아닌, HTTP 프로토콜에 관한 부분입니다.

 

다중 파일 업로드

여러 개의 파일을 동시에 업로드하는 것이 가능합니다.

 

이것은 "폼 데이터"를 사용하여 전달된 동일한 "폼 필드"와 연관되어 있습니다.

 

그것을 사용하려면, bytes 또는 UploadFile 의 List 를 선언하기 바랍니다:

 

 

선언된 대로, bytes 또는 UploadFile 의 list 를 전달 받습니다.

 

참고

2019-04-14 이후, Swagger UI는 동일한 폼 필드 속 다중 파일 업로드를 지원하지 않는다는 걸 잊지마시기 바랍니다. 더 많은 정보는, #4276 및 #3641 을 확인하기 바랍니다.

그럼에도 불구하고, FastAPI는 이미, 표준 OpenAPI를 사용하여, 그것과 호환할 수 있습니다.

따라서, Swagger UI의 다중-파일 업로드 지원, 또는 OpenAPI를 지원하는 어떤 다른 도구와 무관하게, 그것들은 FastAPI와 호환됩니다.

 

기술적 세부사항

from starlette.responses import HTMLResponse 를 사용할 수 있습니다.

FastAPI는 개발자의 편의성을 위해 starlette.responses 와 동일한 fastapi.responses 를 제공합니다. 그러나 대부분의 사용가능한 응답은 Starlette으로부터 직접 전달 받습니다.

 

요약

업로드할 파일을 (폼 데이터인) 입력 매개변수로 선언하기 위해 File 을 사용하기 바랍니다.

 

 

---

원문

https://fastapi.tiangolo.com/tutorial/request-files/

Request Files - FastAPI