이 문서에서는 파일 이름 지정 및 색인이 생성 가능한 텍스트, 썸네일과 같은 메타데이터 작업에 관한 중요한 고려사항을 다룹니다. 파일을 삽입하고 검색하려면 files 리소스를 참고하세요.
파일 이름 및 확장자 지정
앱은 Google Drive API로 파일을 삽입할 때 제목 속성에서 파일 확장자를 지정해야 합니다. 예를 들어 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>를 저장하면 '여기에 텍스트가 있습니다'에 색인이 생성되지만 'value1'에는 색인이 생성되지 않습니다. 따라서 XML을 색인 생성 가능한 텍스트로 저장하는 것은 HTML을 저장하는 것만큼 유용하지 않습니다.
indexableText를 지정할 때는 다음 사항에도 유의하세요.
contentHints.indexableText의 크기 제한은 128KB입니다.- 사용자가 검색할 것으로 예상되는 주요 용어와 개념을 포착합니다.
- 색인 생성 도구가 효율적으로 처리하므로 텍스트를 중요도 순으로 정렬하려고 하지 마세요.
- 애플리케이션은 저장할 때마다 색인을 생성할 수 있는 텍스트를 업데이트해야 합니다.
- 텍스트가 파일의 콘텐츠 또는 메타데이터와 관련이 있는지 확인합니다.
이 마지막 사항은 당연한 것처럼 보이지만 중요합니다. 파일을 검색 결과에 강제로 표시하기 위해 일반적으로 검색되는 검색어를 추가하는 것은 좋지 않습니다. 이로 인해 사용자에게 불만이 생기고 파일을 삭제하려는 동기가 생길 수 있습니다.
썸네일 업로드
Drive는 Google Docs, Sheets, Slides와 같은 여러 일반적인 파일 형식의 썸네일을 자동으로 생성합니다. 썸네일은 사용자가 Drive 파일을 더 잘 식별하는 데 도움이 됩니다.
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 필드에 있습니다.
특정 썸네일 반환
다음 코드 샘플은 여러 필드를 쿼리 매개변수로 사용하는 files.get 메서드 요청을 보여줍니다. 이 요청은 특정 파일의 thumbnailLink 메타데이터를 반환합니다. 자세한 내용은 파일의 특정 필드 반환을 참고하세요.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
FILE_ID를 찾으려는 파일의 fileId로 바꿉니다.
가능한 경우 요청은 파일 썸네일의 단기 URL을 반환합니다.
일반적으로 링크는 몇 시간 동안 유지됩니다. 이 필드는 요청하는 앱이 파일의 콘텐츠에 액세스할 수 있는 경우에만 채워집니다. 파일이 공개적으로 공유되지 않은 경우 thumbnailLink에 반환된 URL은 사용자 인증 정보가 포함된 요청을 사용하여 가져와야 합니다.
썸네일 목록 반환
다음 코드 샘플은 여러 필드를 쿼리 매개변수로 사용하는 files.list 메서드 요청을 보여줍니다. 이 요청은 파일 목록의 thumbnailLink 메타데이터를 반환합니다. 자세한 내용은 파일 및 폴더 검색을 참고하세요.
GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)
검색 결과를 특정 파일 형식으로 제한하려면 쿼리 문자열을 적용하여 MIME 유형을 설정하세요. 예를 들어 다음 코드 샘플은 목록을 Google Sheets 파일로 제한하는 방법을 보여줍니다. 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)