파일 만들기 및 관리

이 가이드에서는 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 필드만 반환합니다. 다른 필드를 반환하려면 특정 필드 반환을 참고하세요.

파일과 함께 사용할 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 상태 코드 응답이 반환되고 중복 파일이 생성되지 않습니다.

application/vnd.google-apps.drive-sdk 및 application/vnd.google-apps.folder MIME 유형을 제외하고 사전 생성된 ID는 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 할당량 한도를 초과할 수 있습니다. 자세한 내용은 사용량 한도를 참고하세요.

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