이 문서에서는 파일 이름 지정 및 색인 생성 가능한 텍스트, 썸네일과 같은 메타데이터 작업에 관한 중요한 고려사항을 다룹니다. 파일을 삽입하고 검색하려면
files 리소스를 참고하세요.
메타데이터 개요
Google Drive API에서 files 리소스는 메타데이터를 나타냅니다. 메타데이터가 하위 객체인 API와 달리 Drive API는 전체 files 리소스를 메타데이터로 취급합니다. files 리소스의
get 또는 list 메서드를 통해 메타데이터에 직접 액세스할 수 있습니다.
기본적으로 get 및 list 메서드는 필드의 일부 집합만 반환합니다. 특정 데이터를 검색하려면 요청에서 fields 시스템 파라미터를 정의해야 합니다. 생략하면 서버는 메서드와 관련된 기본 필드 하위 집합을 반환합니다. 예를 들어 list 메서드는 각 파일의 kind, id, name, mimeType, resourceKey 필드만 반환합니다. 다른
필드를 반환하려면 특정 필드 반환을 참고하세요.
또한 메타데이터 가시성은 파일에 대한 사용자의 역할에 따라 다릅니다.
permissions 리소스는
파일 또는 폴더에 대한 사용자의 허용된 작업을 결정하지 않습니다. 대신 files 리소스
에는 불리언
capabilities 필드 모음이 포함되어 있습니다. Google Drive API는 파일 또는 폴더와 연결된 permissions 리소스에서 이러한 capabilities를 파생시킵니다. 자세한 내용은 파일 기능
이해를 참고하세요.
Drive API는 두 가지 제한된 메타데이터 범위를 제공합니다. drive.metadata
및 drive.metadata.readonly. drive.metadata 범위를 사용하면 파일 메타데이터를 보고
관리할 수 있으며 drive.metadata.readonly는 읽기 전용입니다. 둘 다 파일 콘텐츠에 대한 액세스를 엄격하게 금지합니다. 자세한 내용은 Google Drive API 범위 선택하기를 참고하세요.
마지막으로 권한 및 범위와 관련된 로직을 항상 확인하세요. 예를 들어 사용자에게 모든 권한이 있는 파일이 있을 수 있지만 앱에 drive.metadata.readonly 범위만 있는 경우 Drive API는 파일 수정 또는 다운로드 시도를 차단합니다.
파일 이름 및 확장자 지정
앱은 Google Drive API로 파일을 삽입할 때
name) 속성에
파일 확장자를 지정해야 합니다. 예를 들어 JPEG 파일을 삽입하는 작업
은 메타데이터에 "name": "cat.jpg"와 같은 항목을 지정해야 합니다.
후속 GET 응답에는 읽기 전용 fileExtension 속성이
name 속성에 원래 지정된 확장자로 채워져 포함될 수 있습니다. 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 파일을 더 잘 식별할 수 있습니다.
Drive에서 표준 썸네일을 생성할 수 없는 파일 형식의 경우 애플리케이션에서 생성한 썸네일 이미지를 제공할 수 있습니다. 파일을 만들거나 업데이트하는 동안
contentHints.thumbnail 필드를 files 리소스에서 설정하여 썸네일을 업로드합니다.
구체적인 내용은 다음과 같습니다.
contentHints.thumbnail.image필드를 URL 및 파일 이름 안전 base64로 인코딩된 이미지로 설정합니다 (RFC 4648 섹션 5 참고).contentHints.thumbnail.mimeType필드를 썸네일에 적합한 MIME 유형으로 설정합니다.
Drive에서 파일에서 썸네일을 생성할 수 있는 경우 자동으로 생성된 썸네일을 사용하고 업로드한 썸네일은 무시합니다. 썸네일을 생성할 수 없는 경우 제공한 썸네일을 사용합니다.
썸네일은 다음 규칙을 준수해야 합니다.
- PNG, GIF 또는 JPG 형식으로 업로드할 수 있습니다.
- 권장 너비는 1,600픽셀입니다.
- 최소 너비는 220픽셀입니다.
- 최대 파일 크기는 2MB입니다.
- 저장할 때마다 애플리케이션에서 업데이트해야 합니다.
자세한 내용은 files 리소스를 참고하세요.
썸네일 검색
Drive 파일의 썸네일을 비롯한 메타데이터를 검색할 수 있습니다.
썸네일 정보는
thumbnailLink 필드의
files 리소스에 있습니다.
특정 썸네일 반환
다음 코드 샘플은 특정 파일의 thumbnailLink
메타데이터를 반환하기 위해 여러 필드를 쿼리 매개변수로 사용하는 get 메서드
요청을 보여줍니다. 자세한 내용은 파일의 특정 필드 반환
을 참고하세요.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
FILE_ID를 찾으려는 파일의 fileId로 바꿉니다.
요청은 사용 가능한 경우 파일의 썸네일에 대한 수명이 짧은 URL을 반환합니다.
일반적으로 링크는 몇 시간 동안 지속됩니다. 필드는 요청 앱이 파일의 콘텐츠에 액세스할 수 있는 경우에만 채워집니다. 파일이 공개적으로 공유되지 않는 경우 thumbnailLink에 반환된 URL은 사용자 인증 정보가 있는 요청을 사용하여 가져와야 합니다.
썸네일 목록 반환
다음 코드 샘플은 파일 목록의 thumbnailLink 메타데이터를 반환하기 위해 여러 필드를 쿼리 매개변수로 사용하는 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)