이 문서에서는 파일 이름을 지정하고 색인 생성 가능한 텍스트 및 썸네일과 같은 메타데이터를 사용할 때 고려해야 할 중요한 사항을 설명합니다. 파일을 삽입하고 검색하려면 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>를 저장하면 'Here's some text'는 색인이 생성되지만 'value1'은 색인이 생성되지 않습니다. 따라서 XML을 색인 생성 가능한 텍스트로 저장하는 것은 HTML을 저장하는 것만큼 유용하지 않습니다.
indexableText를 지정할 때는 다음 사항도 고려하세요.
contentHints.indexableText의 크기 제한은 128KB입니다.- 사용자가 검색할 것으로 예상되는 주요 용어와 개념을 파악합니다.
- 색인 생성기가 효율적으로 처리하므로 중요도 순으로 텍스트를 정렬하려고 하지 마세요.
- 애플리케이션은 저장할 때마다 색인 생성 가능한 텍스트를 업데이트해야 합니다.
- 텍스트가 파일의 콘텐츠 또는 메타데이터와 관련이 있는지 확인합니다.
마지막 사항은 당연해 보일 수 있지만 중요합니다. 파일이 검색 결과에 표시되도록 강제하기 위해 일반적으로 검색되는 용어를 추가하는 것은 좋지 않습니다. 이로 인해 사용자가 불만을 느낄 수 있으며 파일을 삭제하도록 유도할 수도 있습니다.
썸네일 업로드
드라이브는 Google Docs, Sheets, Slides와 같은 일반적인 파일 유형의 썸네일을 자동으로 생성합니다. 미리보기 이미지를 사용하면 사용자가 Drive 파일을 더 쉽게 식별할 수 있습니다.
Drive에서 표준 썸네일을 생성할 수 없는 파일 유형의 경우 애플리케이션에서 생성한 썸네일 이미지를 제공할 수 있습니다. 파일을 만들거나 업데이트하는 동안 files 리소스에서 contentHints.thumbnail 필드를 설정하여 썸네일을 업로드합니다.
구체적인 내용은 다음과 같습니다.
contentHints.thumbnail.image필드를 URL 및 파일 이름 안전 base64로 인코딩된 이미지로 설정합니다 (RFC 4648 섹션 5 참고).contentHints.thumbnail.mimeType필드를 썸네일의 적절한 MIME 유형으로 설정합니다.
드라이브에서 파일의 썸네일을 생성할 수 있는 경우 자동으로 생성된 썸네일을 사용하고 사용자가 업로드한 썸네일은 무시합니다. 썸네일을 생성할 수 없는 경우 사용자가 제공한 썸네일을 사용합니다.
썸네일은 다음 규칙을 준수해야 합니다.
- PNG, GIF 또는 JPG 형식으로 업로드할 수 있습니다.
- 권장 너비는 1,600픽셀입니다.
- 최소 너비는 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 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)