맞춤 파일 속성 추가

커스텀 파일 속성은 Google Drive 파일의 커스텀 메타데이터 (예: 태그), 다른 데이터 스토어의 ID, 워크플로 애플리케이션 간에 공유되는 정보 등을 저장하는 데 사용되는 키-값 쌍입니다. 예를 들어 1분기에 영업 부서에서 생성된 모든 문서에 파일 속성을 추가할 수 있습니다.

모든 애플리케이션에 표시되는 속성을 추가하려면 files 리소스의 properties 필드를 사용합니다. 앱에 제한된 속성을 추가하려면 files 리소스의 appProperties 필드를 사용합니다.

속성은 검색 표현식에서도 사용할 수 있습니다.

이는 Drive 파일의 데이터베이스 ID를 파일에 저장하는 데 사용할 수 있는 일반적인 속성의 구조입니다.

Drive API v3

"appProperties": {
  "additionalID": "ID",
}

Drive API v2

{
  'key':        'additionalID',
  'value':      'ID',
  'visibility': 'PRIVATE'
}

커스텀 파일 속성 작업

이 섹션에서는 모든 애플리케이션에 영향을 미치는 맞춤 파일 속성 관련 작업을 실행하는 방법을 설명합니다.

맞춤 파일 속성 추가 또는 업데이트

모든 애플리케이션에 표시되는 속성을 추가하거나 업데이트하려면 files.update 메서드를 사용하여 files 리소스의 properties 필드를 설정합니다.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Google Apps Script에서 고급 드라이브 서비스를 사용하여 파일에 커스텀 속성을 추가할 수도 있습니다. 자세한 내용은 커스텀 속성 추가를 참고하세요.

커스텀 파일 속성 가져오기 또는 나열

모든 애플리케이션에 표시되는 속성을 보려면 files.get 메서드를 사용하여 파일의 커스텀 파일 속성을 가져옵니다.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=properties

응답은 키-값 쌍 컬렉션이 포함된 properties 객체로 구성됩니다.

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

맞춤 파일 속성 삭제

모든 애플리케이션에 표시되는 속성 값을 삭제하려면 files.update 메서드를 사용하여 files 리소스의 properties 필드를 null로 설정합니다.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{
  "name": null
}

변경사항을 보려면 files.get 메서드를 호출하여 파일의 properties 객체를 검색합니다.

{
  "properties": {
    "mass": "1.3kg",
    "count": "3"
  }
}

커스텀 파일 속성의 제한사항

맞춤 속성에는 다음과 같은 한도가 있습니다.

  • 파일당 최대 100개의 맞춤 속성을 모든 소스에서 합산합니다.
  • 파일당 최대 30개의 공개 속성을 모든 소스에서 합산합니다.
  • 한 애플리케이션에서 파일당 최대 30개의 비공개 속성을 사용할 수 있습니다.
  • UTF-8 인코딩에서는 속성 문자열 (키와 값 모두 포함)당 최대 124바이트가 사용됩니다. 예를 들어 길이가 10자인 키가 포함된 속성은 값에 114자만 포함할 수 있습니다. 마찬가지로 값에 100자(영문 기준)가 필요한 속성은 키에 최대 24자(영문 기준)를 사용할 수 있습니다.

자세한 내용은 files 리소스를 참고하세요. Drive API v2의 경우 properties 리소스를 참고하세요.

비공개 맞춤 파일 속성 액세스

OAuth 2.0 클라이언트 ID로 얻은 액세스 토큰을 사용하는 인증된 요청을 통해 appProperties 필드를 사용하는 비공개 속성만 검색할 수 있습니다. API 키를 사용하여 비공개 속성을 가져올 수 없습니다.