장기 실행 작업 관리

장기 실행 작업 (LRO)은 API 응답에 적합한 것보다 완료하는 데 시간이 더 오래 걸리는 API 메서드입니다. 일반적으로 작업이 실행되는 동안 호출 스레드를 열어 두면 사용자 환경이 좋지 않으므로 피하는 것이 좋습니다. 대신 사용자에게 어떤 유형의 약속을 반환하고 나중에 다시 확인하도록 허용하는 것이 좋습니다.

Google Drive API는 Drive API 또는 클라이언트 라이브러리를 통해 파일의 콘텐츠를 다운로드하기 위해 files 리소스에서 download() 메서드를 호출할 때마다 LRO를 반환합니다.

이 메서드는 클라이언트에 operations 리소스를 반환합니다. operations 리소스를 사용하여 get() 메서드를 통해 작업을 폴링하여 API 메서드 상태를 비동기식으로 검색할 수 있습니다. Drive API의 LRO는 Google Cloud LRO 디자인 패턴을 준수합니다.

자세한 내용은 장기 실행 작업을 참고하세요.

참고: files.download() 메서드와 operations.get() 메서드 모두 일반 Drive API 할당량을 사용합니다. 자세한 내용은 사용량 한도를 참고하세요.

프로세스 개요

다음 다이어그램은 file.download 메서드의 작동 방식을 간략하게 보여줍니다.

그림 1. file.download 메서드의 대략적인 단계입니다.

1. files.download 호출: 앱에서 download() 메서드를 호출하면 파일에 대한 Drive API 다운로드 요청이 실행됩니다. 자세한 내용은 파일 다운로드를 참고하세요.

2. 권한 요청: 이 요청은 Drive API에 사용자 인증 정보를 전송합니다. 앱에 아직 부여되지 않은 사용자 인증을 사용하여 Drive API를 호출해야 하는 경우 사용자에게 로그인하라는 메시지가 표시됩니다. 또한 앱은 인증을 설정할 때 지정한 범위를 사용하여 액세스를 요청합니다.

3. 다운로드 시작: 파일 다운로드를 시작하기 위해 Drive API 요청이 이루어집니다. Google Vids 또는 기타 Google Workspace 콘텐츠에 대한 요청이 있을 수 있습니다.

4. LRO 시작: 장기 실행 작업이 시작되고 다운로드 프로세스를 관리합니다.

5. 대기 중인 작업 반환: Drive API는 요청하는 사용자에 관한 정보와 여러 파일 메타데이터 필드가 포함된 대기 중인 작업을 반환합니다.

6. 초기 대기 중 상태: 앱은 초기 대기 중 상태인 done=null와 함께 대기 중인 작업을 수신합니다. 이는 파일을 아직 다운로드할 수 없으며 작업 상태가 대기 중임을 나타냅니다.

7. operations.get 호출 및 결과 확인: 앱은 권장 간격으로 get()를 호출하여 작업 결과를 폴링하고 장기 실행 작업의 최신 상태를 가져옵니다. 대기 중인 done=false 상태가 반환되면 작업이 완료된 상태 (done=true)를 반환할 때까지 앱이 계속 폴링해야 합니다. 대용량 파일의 경우 여러 번 폴링해야 할 수 있습니다. 자세한 내용은 장기 실행 작업에 관한 세부정보 가져오기를 참고하세요.

8. 대기 중인 상태 확인: LRO에서 대기 중인 상태 done=true가 반환되면 파일을 다운로드할 준비가 되었으며 작업 상태가 완료되었음을 나타냅니다.

9. 다운로드 URI와 함께 완료된 작업 반환: LRO가 완료되면 Drive API가 다운로드 URI를 반환하고 이제 사용자는 파일을 사용할 수 있습니다.

파일 다운로드

장기 실행 작업에서 콘텐츠를 다운로드하려면 files 리소스에서 download() 메서드를 사용합니다. 이 메서드는 file_id, mime_type, revision_id의 쿼리 매개변수를 사용합니다.

• 필수 항목입니다. file_id 쿼리 매개변수는 다운로드할 파일의 ID입니다.

• 선택사항입니다. mime_type 쿼리 매개변수는 메서드에서 사용해야 하는 MIME 유형을 나타냅니다. blob이 아닌 미디어 콘텐츠(예: Google Workspace 문서)를 다운로드할 때만 사용할 수 있습니다. 지원되는 MIME 유형의 전체 목록은 Google Workspace 문서의 MIME 유형 내보내기를 참고하세요.

  MIME 유형이 설정되지 않으면 Google Workspace 문서가 기본 MIME 유형으로 다운로드됩니다. 자세한 내용은 기본 MIME 유형을 참고하세요.

• 선택사항입니다. revision_id 쿼리 매개변수는 다운로드할 파일의 버전 ID입니다. blob 파일, Google Docs, Google Sheets를 다운로드할 때만 사용할 수 있습니다. 지원되지 않는 파일의 특정 버전을 다운로드할 때 오류 코드 INVALID_ARGUMENT를 반환합니다.

download() 메서드는 Vids 파일을 MP4 형식으로 다운로드하는 유일한 방법이며 일반적으로 대부분의 동영상 파일을 다운로드하는 데 가장 적합합니다.

Google Docs 또는 Sheets용으로 생성된 다운로드 링크는 처음에 리디렉션을 반환합니다. 새 링크를 클릭하여 파일을 다운로드합니다.

LRO를 시작하는 download() 메서드에 대한 요청과 최종 다운로드 URI를 가져오는 요청은 모두 리소스 키를 사용해야 합니다. 자세한 내용은 리소스 키를 사용하여 링크 공유 Drive 파일에 액세스를 참고하세요.

요청 프로토콜은 다음과 같습니다.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

FILE_ID를 다운로드하려는 파일의 fileId로 바꿉니다.

참고: download() 메서드는 Drive API v3에서만 사용할 수 있습니다.

기본 MIME 유형

blob이 아닌 콘텐츠를 다운로드할 때 MIME 유형이 설정되지 않으면 다음과 같은 기본 MIME 유형이 할당됩니다.

문서 유형	형식	MIME 유형	파일 확장자
Google Apps Script	JSON	application/vnd.google-apps.script+json	.json
Google Docs	Microsoft Word	application/vnd.openxmlformats-officedocument.wordprocessingml.document	.docx
Google Drawings	PNG	image/png	.png
Google Forms	우편번호	application/zip	.zip
Google Sheets	Microsoft Excel	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	.xlsx
Google Sites	원시 텍스트	text/raw	.txt
Google Slides	Microsoft PowerPoint	application/vnd.openxmlformats-officedocument.presentationml.presentation	.pptx
Google Vids	MP4	application/mp4	.mp4
Jamboard	PDF	application/pdf	.pdf

응답 다운로드

download() 메서드를 호출할 때 응답 본문은 장기 실행 작업을 나타내는 리소스로 구성됩니다. 이 메서드는 일반적으로 파일 콘텐츠를 다운로드할 수 있는 링크를 반환합니다.

도움말: LRO를 폴링하는 데 필요하므로 name 필드 값을 저장합니다.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

이 출력에는 다음 값이 포함됩니다.

• RESOURCE_KEY: 리소스 키는 의도치 않은 액세스로부터 파일을 보호하는 데 도움이 됩니다. 자세한 내용은 리소스 키를 사용하여 링크 공유 Drive 파일에 액세스를 참고하세요.

• NAME: 서버에서 할당한 이름입니다.

• DOWNLOAD_URI: 파일의 최종 다운로드 URI입니다.

partialDownloadAllowed 필드는 부분 다운로드가 허용되는지를 나타냅니다. blob 파일 콘텐츠를 다운로드할 때 true입니다.

장기 실행 작업에 대한 세부정보 가져오기

장기 실행 작업은 완료하는 데 상당한 시간이 걸릴 수 있는 메서드 호출입니다. 일반적으로 새로 생성된 다운로드 작업은 특히 Vids 파일의 경우 처음에 대기 중인 상태 (done=null)로 반환됩니다.

Drive API에서 제공하는 operations 리소스를 사용하여 고유한 서버 할당 이름을 포함하여 처리 중인 LRO의 상태를 확인할 수 있습니다.

get() 메서드는 장기 실행 작업의 최신 상태를 비동기식으로 가져옵니다. 클라이언트는 이 메서드를 사용하여 API 서비스가 권장하는 간격으로 작업 결과를 폴링할 수 있습니다.

참고: get() 메서드 요청을 실행하는 사용자는 인접한 download() 메서드 요청을 시작한 사용자와 일치해야 합니다. 그렇지 않으면 요청이 실패합니다.

장기 실행 작업 폴링

사용 가능한 LRO를 폴링하려면 작업이 완료될 때까지 get() 메서드를 반복해서 호출합니다. 각 폴링 요청 사이에 지수 백오프를 사용합니다(예: 10초).

LRO는 최소 12시간 동안 사용할 수 있지만 경우에 따라 더 오래 지속될 수 있습니다. 이 기간은 변경될 수 있으며 파일 형식에 따라 다를 수 있습니다. 리소스가 만료되면 새 download() 메서드 요청이 필요합니다.

get()에 대한 모든 요청은 리소스 키를 사용해야 합니다. 자세한 내용은 리소스 키를 사용하여 링크 공유 Drive 파일에 액세스하기를 참고하세요.

요청 프로토콜은 여기에 표시됩니다.

메서드 호출

operations.get(name='NAME');

NAME을 download() 메서드 요청의 응답에 표시된 대로 작업의 서버 할당 이름으로 바꿉니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다 . gcloud auth list를 실행하면 활성 계정을 확인할 수 있습니다.

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

NAME을 download() 메서드 요청에 대한 응답에 표시된 대로 작업의 서버 할당 이름으로 바꿉니다.

이 명령어는 경로 /drive/v3/operations/NAME를 사용합니다.

name는 download() 요청에 대한 응답에서만 반환됩니다. Drive API가 List() 메서드를 지원하지 않으므로 이를 가져오는 다른 방법은 없습니다. name 값이 손실되면 download() 메서드 요청을 다시 호출하여 새 응답을 생성해야 합니다.

get() 요청의 응답은 장기 실행 작업을 나타내는 리소스로 구성됩니다. 자세한 내용은 응답 다운로드를 참고하세요.

응답에 완료된 상태 (done=true)가 포함되면 장기 실행 작업이 완료된 것입니다.

버전 다운로드

files 리소스의 headRevisionId 필드 값을 사용하여 최신 버전을 다운로드할 수 있습니다. 이렇게 하면 이전에 가져온 파일의 메타데이터에 해당하는 버전이 가져옵니다. 클라우드에 아직 저장되어 있는 파일의 이전 버전의 모든 데이터를 다운로드하려면 fileId 매개변수를 사용하여 revisions 리소스에서 list() 메서드를 호출하면 됩니다. 이렇게 하면 파일의 모든 revisionIds가 반환됩니다.

참고: 이전 버전에 대한 액세스는 역할에 따라 제한됩니다. 액세스를 시도하기 전에 files 리소스의 capabilities.canReadRevisions 필드를 확인합니다.

blob 파일의 버전 콘텐츠를 다운로드하려면 다운로드할 파일의 ID, 버전의 ID, alt=media URL 매개변수를 사용하여 revisions 리소스에서 get() 메서드를 호출해야 합니다. alt=media URL 매개변수는 콘텐츠 다운로드가 대체 응답 형식으로 요청되고 있다고 서버에 알립니다.

Google Docs, Sheets, Slides, 동영상의 수정사항은 alt=media URL과 함께 get() 메서드를 사용하여 다운로드할 수 없습니다 . 그렇지 않으면 fileNotDownloadable 오류가 발생합니다.

alt=media URL 매개변수는 모든 Google REST API에서 사용할 수 있는 시스템 매개변수입니다. Drive API에 클라이언트 라이브러리를 사용하는 경우 이 매개변수를 명시적으로 설정할 필요가 없습니다.

요청 프로토콜은 다음과 같습니다.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

다음을 바꿉니다.

• FILE_ID: 다운로드할 파일의 fileId입니다.
• REVISION_ID: 다운로드할 버전의 revisionId입니다.

참고: 이전 Drive API v2를 사용하는 경우 downloadUrl 속성에 승인된 GET 요청을 전송해야 합니다. Google Drive는 수정을 요청할 때 이 짧은 시간 동안 유효한 URL을 생성하지만 나중에 사용하기 위해 이 URL을 사용하지 마세요. exportLinks 속성을 선택하여 지원되는 형식 중 하나로 버전을 내보낼 수도 있습니다.

Google Docs, Drawings, Slides 버전은 버전 번호를 자동으로 증분합니다. 그러나 수정사항이 삭제되면 일련번호 사이에 간격이 생길 수 있으므로 순차 번호를 사용하여 수정사항을 검색해서는 안 됩니다.

LRO 문제 해결

LRO가 실패하면 응답에 표준 Google Cloud 오류 코드가 포함됩니다.

다음 표에서는 각 코드의 원인에 대한 설명과 코드 처리 방법에 대한 권장사항을 보여줍니다. 많은 오류의 경우 지수 백오프를 사용해서 요청을 다시 시도하는 것이 좋습니다.

API 설계 가이드에서 이 오류 모델과 모델 작업 방법에 대해 자세히 알아볼 수 있습니다.

코드	Enum	설명	권장 조치
1	CANCELLED	작업이 취소되었습니다. 대개 호출자에 의해 취소됩니다.	작업을 다시 실행합니다.
2	UNKNOWN	다른 주소 공간에서 수신된 Status 값이 이 주소 공간에서 알려지지 않은 오류 공간에 속하는 경우 이 오류가 반환될 수 있습니다. API 오류가 충분한 정보를 반환하지 않으면 해당 오류가 이 오류로 변환될 수 있습니다.	지수 백오프로 다시 시도합니다.
3	INVALID_ARGUMENT	클라이언트에서 잘못된 인수를 지정했습니다. 이 오류는 FAILED_PRECONDITION과 다릅니다. INVALID_ARGUMENT는 시스템 상태에 관계없이 문제(예: 잘못된 형식의 파일 이름)가 있는 인수를 나타냅니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
4	DEADLINE_EXCEEDED	작업을 완료하기 전에 기한이 지났습니다. 작업에서 시스템의 상태를 변경하는 경우 작업이 정상적으로 완료되었어도 이 오류가 반환될 수 있습니다. 예를 들어 서버의 성공 응답이 오래 지연되어 기한이 지났을 수 있습니다.	지수 백오프로 다시 시도합니다.
5	NOT_FOUND	FHIR 리소스와 같은 일부 요청한 항목을 찾을 수 없습니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
6	ALREADY_EXISTS	클라이언트에서 만들려고 시도한 항목(예: DICOM 인스턴스)이 이미 존재합니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
7	PERMISSION_DENIED	호출자에 지정한 작업을 실행할 권한이 없습니다. 이 오류 코드는 요청이 유효하다거나, 요청된 항목이 존재한다거나, 다른 전제조건이 충족되었음을 의미하지 않습니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
8	RESOURCE_EXHAUSTED	프로젝트당 할당량과 같은 일부 리소스가 소진되었습니다.	지수 백오프로 다시 시도합니다. 할당량은 시간 경과에 따라 사용 가능해질 수 있습니다.
9	FAILED_PRECONDITION	시스템이 작업 실행에 필요한 상태가 아니기 때문에 작업이 거부되었습니다. 예를 들어 삭제할 디렉토리가 비어 있지 않거나 디렉토리가 아닌 항목에 rmdir 작업을 적용한 경우입니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
10	ABORTED	작업이 취소되었습니다. 대개 시퀀서 확인 실패, 트랜잭션 취소 등의 동시 실행 문제가 원인입니다.	지수 백오프로 다시 시도합니다.
11	OUT_OF_RANGE	파일 끝을 지나서 탐색하거나 읽는 등 유효한 범위를 넘어서 작업을 시도했습니다. INVALID_ARGUMENT와 달리, 이 오류는 시스템 상태가 변경되면 문제가 해결될 수 있음을 나타냅니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
12	UNIMPLEMENTED	작업이 구현되지 않았거나 Drive API에서 지원되지 않거나 사용 설정되지 않았습니다.	재시도하지 마세요.
13	INTERNAL	내부 오류가 발생했습니다. 기본 시스템에서 처리 중에 예기치 않은 오류가 발생했음을 나타냅니다.	지수 백오프로 다시 시도합니다.
14	UNAVAILABLE	Drive API를 사용할 수 없습니다. 일시적인 상태일 가능성이 높으며, 지수 백오프로 다시 시도하면 해결될 수 있습니다. 멱등성이 없는 작업을 재시도하는 것이 항상 안전한 것은 아닙니다.	지수 백오프로 다시 시도합니다.
15	DATA_LOSS	복구할 수 없는 데이터 손실이나 손상이 발생했습니다.	시스템 관리자에게 문의하세요. 데이터 손실 또는 손상이 발생한 경우 시스템 관리자가 지원 담당자에게 연락해야 할 수 있습니다.
16	UNAUTHENTICATED	요청에 작업과 관련된 올바른 사용자 인증 정보가 없습니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.

관련 주제

• 파일 다운로드 및 내보내기
• 파일 버전 관리