텔레그램 API 파일 올리기·받기

파일은 조각으로 오간다

텔레그램 API 에서 파일은 한 번에 보내지 않고 조각(part)으로 나눠 올리고, 받을 때도 위치(offset)와 길이(limit)를 정해 조각씩 받습니다. 공식 앱과 TDLib 은 이 일을 대신 하지만, 직접 구현한다면 조각 크기 규칙을 지켜야 서버가 받아 줍니다.

올리기

파일 크기	메서드	마지막에 넘기는 값
10MB 이하	upload.saveFilePart	inputFile
10MB 초과	upload.saveBigFilePart	inputFileBig

1. 파일마다 내가 고른 무작위 64비트 번호(file_id)를 정합니다.
2. 조각 크기를 정합니다. 1KB 의 배수여야 하고, 512KB 를 나누어떨어지게 해야 합니다(예: 512KB, 256KB, 128KB…). 마지막 조각만 이보다 작아도 됩니다.
3. 조각 번호를 0부터 붙여 차례로 올립니다. 올릴 수 있는 조각 수는 서버 설정 값으로 정해지며, 일반 계정과 프리미엄 계정의 값이 다릅니다.
4. 다 올리면 그 파일 번호를 inputFile(또는 inputFileBig)에 담아 메시지 보내기 같은 요청에 넘깁니다. 작은 파일은 MD5 를 함께 넘기면 서버가 깨짐을 확인합니다.

올린 파일은 올린 데이터 센터에서만 바로 받을 수 있습니다 — 다른 곳에서 받으려면 FILE_MIGRATE 오류대로 옮깁니다(데이터 센터).

받기 — upload.getFile

방식	offset · limit 규칙
기본	둘 다 4KB 의 배수, 그리고 1MB 를 limit 으로 나누어떨어져야 한다
precise 켬	둘 다 1KB 의 배수, limit 은 1MB 까지
공통	요청한 범위가 1MB 단위 구간 하나를 넘어가면 안 된다

• 큰 파일은 별도 연결을 여러 개 열어 나눠 받는 편이 빠릅니다. 이런 연결은 업데이트를 받지 않게 둡니다(메서드 부르기).
• 인기 파일은 CDN 으로 넘기라는 답이 올 수 있습니다. 그때는 안내된 CDN 데이터 센터에서 받고, 받은 조각의 해시를 확인합니다.

자주 만나는 오류

오류	할 일
FILE_MIGRATE_X	X 번 데이터 센터에서 받기
FILE_REFERENCE_EXPIRED	파일 참조가 만료 — 원래 메시지를 다시 받아 새 참조로(파일 참조 만료)
FLOOD_WAIT_X	X 초 기다리기(오류 읽기)

봇 API 로 파일을 보낼 때는 이런 조각 규칙 없이 HTTP 로 올리거나 file_id 를 다시 쓰면 됩니다 — 대신 크기 한도가 따로 있습니다.