파일 메타데이터 관리

이 문서에서는 파일 이름을 지정하고 색인 생성 가능한 텍스트 및 썸네일과 같은 메타데이터 작업을 할 때 중요한 고려사항을 설명합니다. 파일을 삽입하고 검색하려면 files 리소스를 참조하세요.

파일 이름 및 확장자 지정

앱은 Google Drive API를 사용하여 파일을 삽입할 때 title 속성에 파일 확장자를 지정해야 합니다. 예를 들어 JPEG 파일을 삽입하는 작업은 메타데이터에 "name": "cat.jpg"와 같은 항목을 지정해야 합니다.

후속 GET 응답에는 원래 name 속성에 지정된 확장 프로그램으로 채워진 읽기 전용 fileExtension 속성이 포함될 수 있습니다. Google Drive 사용자가 파일 다운로드를 요청하거나 동기화 클라이언트를 통해 파일이 다운로드되면 Drive에서는 제목을 기반으로 전체 파일 이름 (확장자 포함)을 만듭니다. 확장 프로그램이 누락된 경우 Drive는 파일의 MIME 유형에 따라 확장자를 확인하려고 시도합니다.

색인 생성이 가능한 텍스트 저장

Drive가 텍스트 문서, PDF, 텍스트가 포함된 이미지, 기타 일반적인 유형 등 파일 형식을 인식하면 검색할 문서에 자동으로 색인을 생성합니다. 앱이 다른 유형의 파일 (예: 그림, 동영상, 바로가기)을 저장하는 경우 파일의 contentHints.indexableText 필드에 색인을 생성할 수 있는 텍스트를 제공하여 검색 가능성을 개선할 수 있습니다.

색인 생성 가능한 텍스트는 HTML로 색인이 생성됩니다. 색인 생성이 가능한 텍스트 문자열 <section attribute="value1">Here's some text</section>를 저장하면 ' Here's some text'의 색인은 생성되지만 'value1'의 색인은 생성되지 않습니다. 따라서 XML을 색인 생성이 가능한 텍스트로 저장하는 것은 HTML을 저장하는 것만큼 유용하지 않습니다.

indexableText를 지정할 때는 다음에도 유의하세요.

  • contentHints.indexableText의 크기 제한은 128KB입니다.
  • 사용자가 검색할 것으로 예상되는 주요 용어와 개념을 파악합니다.
  • 색인 생성기가 효율적으로 작업을 수행하므로 중요도에 따라 텍스트를 정렬하려고 하지 마세요.
  • 애플리케이션은 저장할 때마다 색인 생성 가능한 텍스트를 업데이트해야 합니다.
  • 텍스트가 파일의 콘텐츠 또는 메타데이터와 관련이 있는지 확인하세요.

이 마지막 요점은 당연해 보일 수 있지만 중요합니다. 일반적으로 검색어를 추가하여 검색결과에 파일을 강제로 표시하는 것은 바람직하지 않습니다. 이로 인해 사용자가 실망할 수 있고 파일을 삭제하게 될 수도 있습니다.

썸네일 업로드

Drive는 Google Docs, Sheets, Slides와 같은 여러 일반적인 파일 형식의 썸네일을 자동으로 생성합니다. 썸네일은 사용자가 Drive 파일을 더 잘 식별하는 데 도움이 됩니다.

드라이브에서 표준 썸네일을 생성할 수 없는 파일 형식의 경우 애플리케이션에서 생성한 썸네일 이미지를 제공할 수 있습니다. 파일 생성 또는 업데이트 중에 files 리소스에서 contentHints.thumbnail 필드를 설정하여 썸네일을 업로드합니다.

특히 다음에 주의해야 합니다.

  • contentHints.thumbnail.image 필드를 URL 및 파일 이름 안전 base64 인코딩 이미지로 설정합니다 (RFC 4648 섹션 5 참고).
  • contentHints.thumbnail.mimeType 필드를 썸네일의 적절한 MIME 유형으로 설정합니다.

Drive가 파일에서 썸네일을 생성할 수 있는 경우, 자동으로 생성된 썸네일을 사용하고 사용자가 업로드한 썸네일은 무시합니다. 썸네일을 생성할 수 없으면 제공된 썸네일을 사용합니다.

썸네일은 다음 규칙을 준수해야 합니다.

  • PNG, GIF, JPG 형식으로 업로드할 수 있습니다.
  • 권장 너비는 1600픽셀입니다.
  • 최소 너비는 220픽셀입니다.
  • 최대 파일 크기는 2MB입니다.
  • 저장할 때마다 애플리케이션에서 업데이트해야 합니다.

자세한 내용은 files 리소스를 참고하세요.

썸네일 검색

Drive 파일의 썸네일을 비롯한 메타데이터를 검색할 수 있습니다. 썸네일 정보는 files 리소스의 thumbnailLink 필드에 저장됩니다.

특정 썸네일 반환

다음 코드 샘플은 특정 파일의 thumbnailLink 메타데이터를 반환하기 위한 쿼리 매개변수로 여러 필드가 포함된 files.get 메서드 요청을 보여줍니다. 자세한 내용은 파일의 특정 필드 반환을 참고하세요.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

FILE_ID를 검색하려는 파일의 fileId로 바꿉니다.

가능한 경우 요청은 파일의 썸네일에 단기 URL을 반환합니다. 일반적으로 링크는 몇 시간 동안 지속됩니다. 이 필드는 요청하는 앱이 파일의 콘텐츠에 액세스할 수 있는 경우에만 채워집니다. 파일이 공개적으로 공유되지 않은 경우 사용자 인증 정보 요청을 사용하여 thumbnailLink에서 반환된 URL을 가져와야 합니다.

썸네일 목록 반환

다음 코드 샘플은 파일 목록의 thumbnailLink 메타데이터를 반환하기 위한 쿼리 매개변수로 여러 필드가 포함된 files.list 메서드 요청을 보여줍니다. 자세한 내용은 파일 및 폴더 검색을 참조하세요.

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

검색 결과를 특정 파일 형식으로 제한하려면 쿼리 문자열을 적용하여 MIME 유형을 설정합니다. 예를 들어 다음 코드 샘플은 목록을 Google 스프레드시트 파일로 제한하는 방법을 보여줍니다. MIME 유형에 관한 자세한 내용은 Google Workspace 및 Google Drive에서 지원하는 MIME 유형을 참고하세요.

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)