파일 만들기 및 관리

이 가이드에서는 Google Drive API를 사용하여 Google Drive에서 파일을 만들고 관리하는 방법을 설명합니다.

파일 만들기

메타데이터나 콘텐츠가 포함되지 않은 파일을 Drive에 만들려면 매개변수 없이 files 리소스에서 create 메서드를 사용합니다.

파일을 만들면 메서드가 files 리소스를 반환합니다. 파일에는 drive.file의 kind, id, '제목 없음'의 name, application/octet-stream의 mimeType이 지정됩니다. uploadType은 필수 항목으로 표시되지만 기본값은 media이므로 실제로 제공하지 않아도 됩니다.

Drive 파일 한도에 대한 자세한 내용은 파일 및 폴더 한도를 참고하세요.

fields 매개변수 사용

응답에서 반환할 필드를 지정하려면 files 리소스의 메서드를 사용하여 fields 시스템 매개변수를 설정하면 됩니다. fields 매개변수를 생략하면 서버는 메서드에 특정한 기본 필드 집합을 반환합니다. 예를 들어 list 메서드는 각 파일에 대해 kind, id, name, mimeType, resourceKey 필드만 반환합니다. 다른 필드를 반환하려면 특정 필드 반환을 참고하세요.

파일 소유권

Drive API를 사용하여 파일을 만들 때 소유권은 앱에서 사용하는 인증 사용자 인증 정보에 따라 다음과 같이 달라집니다.

  • 사용자 계정 (OAuth 2.0): 애플리케이션이 사용자를 대신하여 인증하는 경우 해당 사용자가 파일 소유자가 됩니다. 그러면 파일이 내 드라이브 폴더 또는 지정된 폴더에 저장됩니다. 스토리지 할당량을 소모합니다.

  • 서비스 계정: 애플리케이션이 서비스 계정을 사용하여 인증하는 경우 서비스 계정이 파일 소유자입니다. 그러면 파일이 서비스 계정의 전용 Drive 저장소에 상주합니다. 명시적으로 공유하지 않는 한 파일이 다른 Drive 스토리지 계정에 표시되지 않습니다. 서비스 계정이 삭제되면 소유한 모든 파일이 즉시 삭제됩니다.

    서비스 계정을 사용하지만 특정 사용자 계정이 파일을 소유하도록 하려면 도메인 전체 위임을 사용하세요. 이렇게 하면 서비스 계정이 사용자를 가장하고 사용자를 대신하여 파일을 만들 수 있습니다. 자세한 내용은 서비스 계정에 도메인 전체 권한 위임을 참고하세요.

파일 권한에 대한 자세한 내용은 파일, 폴더, 드라이브 공유하기를 참고하세요.

파일과 함께 사용할 ID 생성

files 리소스의 generateIds 메서드를 사용하면 Drive에서 파일과 폴더를 만들거나 복사할 때 사용할 수 있는 고유한 파일 ID를 미리 생성할 수 있습니다. 이 방법은 Drive에서 자동으로 할당하는 대신 앱에서 파일 ID를 제어해야 하는 경우에 유용할 수 있습니다.

count 쿼리 매개변수를 사용하여 생성되는 ID 수를 설정할 수 있습니다. count이 설정되지 않은 경우 기본적으로 10이 반환됩니다. 요청할 수 있는 ID의 최대 수는 1,000개로 제한됩니다.

ID를 사용할 수 있는 space와 ID를 사용할 수 있는 항목의 type를 지정할 수도 있습니다.

ID가 생성되면 id 필드를 통해 create 또는 copy 메서드에 전달할 수 있습니다. 이렇게 하면 생성되거나 복사된 파일이 미리 정해진 ID를 사용합니다.

파일이 성공적으로 생성되거나 복사되면 후속 재시도에서 409 Conflict HTTP 상태 코드 응답이 반환되고 중복 파일이 생성되지 않습니다.

사전 생성된 ID는 application/vnd.google-apps.drive-sdk 및 application/vnd.google-apps.folder MIME 유형을 제외한 Google Workspace 파일 생성에 지원되지 않습니다. 마찬가지로 Google Workspace 파일 형식으로의 변환을 참조하는 업로드는 지원되지 않습니다.

메타데이터 전용 파일 만들기

메타데이터 전용 파일에는 콘텐츠가 포함되어 있지 않습니다. 메타데이터는 파일을 설명하는 데이터 (예: name, mimeType, createdTime)입니다. name와 같은 필드는 사용자에 구애받지 않으며 각 사용자에게 동일하게 표시되는 반면 viewedByMeTime과 같은 필드에는 사용자별 값이 포함됩니다.

메타데이터 전용 파일의 한 예는 MIME 유형이 application/vnd.google-apps.folder인 폴더입니다. 자세한 내용은 폴더 만들기 및 채우기를 참고하세요. 또 다른 예는 MIME 유형이 application/vnd.google-apps.shortcut인 Drive의 다른 파일을 가리키는 바로가기입니다. 자세한 내용은 Drive 파일 바로가기 만들기를 참고하세요.

썸네일 이미지 관리

썸네일은 사용자가 Drive 파일을 식별하는 데 도움이 됩니다. Drive에서는 일반적인 파일 유형의 썸네일을 자동으로 생성할 수 있으며, 앱에서 생성한 썸네일 이미지를 제공할 수도 있습니다. 자세한 내용은 썸네일 업로드를 참고하세요.

기존 파일 복사

파일을 복사하고 요청된 업데이트를 적용하려면 files 리소스에서 copy 메서드를 사용합니다. 복사할 fileId를 찾으려면 list 메서드를 사용합니다.

패치 시맨틱을 통해 업데이트를 적용할 수 있습니다. 즉, 리소스를 부분적으로 수정할 수 있습니다. 요청에서 수정하려는 필드를 명시적으로 설정해야 합니다. 요청에 포함되지 않은 필드는 기존 값을 유지합니다. 자세한 내용은 부분 리소스 작업을 참고하세요.

generateIds 메서드를 사용하여 복사된 파일의 파일 ID를 미리 설정할 수 있습니다. 자세한 내용은 파일과 함께 사용할 ID 생성을 참고하세요.

호출을 승인하려면 적절한 Drive API 범위를 사용해야 합니다. Drive 범위에 대한 자세한 내용은 Google Drive API 범위 선택하기를 참고하세요.

한도 및 고려사항

파일 복사를 준비할 때 다음 제한사항과 고려사항에 유의하세요.

  • 권한:

    • files 리소스의 DownloadRestrictionsMetadata 객체는 파일을 복사할 수 있는 사용자를 결정합니다. 자세한 내용은 사용자가 파일을 다운로드, 인쇄 또는 복사하지 못하도록 방지하기를 참고하세요.
    • capabilities.canCopy 필드 리소스는 사용자가 파일을 복사할 수 있는지 여부를 결정합니다. 자세한 내용은 파일 기능 이해를 참고하세요.
    • 사본을 만든 사용자가 복사된 파일을 소유합니다. 소스 파일의 다른 공유 설정은 복제되지 않습니다. 사본이 공유 폴더에 생성되면 해당 폴더의 권한이 상속됩니다.
    • 복사된 파일의 소유권이 변경될 수 있으며 복사본이 원본 파일의 공유 설정을 상속하지 않을 수 있습니다. 이러한 설정을 재설정해야 할 수도 있습니다.

  • 파일 관리:

    • 서드 파티 바로가기와 같은 일부 파일은 복사할 수 없습니다.
    • 파일은 하나의 상위 폴더에만 복사할 수 있습니다. 여러 상위 항목을 지정하는 것은 지원되지 않습니다. parents 필드가 지정되지 않은 경우 파일은 소스 파일에서 검색 가능한 상위 요소를 상속합니다.
    • 폴더는 파일의 한 유형이지만 폴더를 복사할 수는 없습니다. 대신 대상 폴더를 만들고 기존 파일의 parents 필드를 대상 폴더로 설정하세요. 그런 다음 원래 소스 폴더를 삭제할 수 있습니다.
    • 새 파일 이름을 지정하지 않으면 copy 메서드는 원본과 동일한 이름의 파일을 생성합니다.
    • copy를 과도하게 사용하면 Drive API 할당량 한도를 초과할 수 있습니다. 자세한 내용은 사용량 한도를 참고하세요.

다음과 같은 몇 가지 단계를 시도해 볼 수 있습니다.