맞춤 파일 속성은 Google Drive 파일의 맞춤 메타데이터 (예: 태그), 다른 데이터 스토어의 ID, 워크플로 애플리케이션 간에 공유되는 정보 등을 저장하는 데 사용되는 키-값 쌍입니다. 예를 들어 1분기에 영업 부서에서 생성한 모든 문서에 파일 속성을 추가할 수 있습니다.
모든 애플리케이션에 표시되는 속성을 추가하려면 files 리소스의 properties 필드를 사용합니다. 앱으로 제한된 속성을 추가하려면 files 리소스의 appProperties 필드를 사용하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-29(UTC)"],[],[],null,["# Add custom file properties\n\n*Custom file properties* are key-value pairs used to store custom metadata for a\nGoogle Drive file (such as tags), IDs from other data stores, information\nshared between workflow applications, and so on. For example, you can add file\nproperties to all documents generated by the sales department in Q1.\n\nTo add properties visible to all applications, use the `properties` field of the\n[`files`](/workspace/drive/api/reference/rest/v3/files) resource. To add properties\nrestricted to your app, use the `appProperties` field of the `files` resource.\n| **Note:** If you're using the older version of Google Drive API (v2), utilize the [`properties`](/workspace/drive/api/reference/rest/v2/properties) resource to add properties to your app using [`properties.insert`](/workspace/drive/api/reference/rest/v2/properties/insert). For a complete list of differences between versions, see the [Drive API v2 \\&\n| v3 comparison reference](/workspace/drive/api/guides/v2-to-v3-reference).\n\nProperties can also be used in [search\nexpressions](/workspace/drive/api/guides/search-files#custom).\n\nThis is the structure of a typical property that might be used to store a\nDrive file's database ID on the file. \n\n### Drive API v3\n\n \"appProperties\": {\n \"additionalID\": \"\u003cvar translate=\"no\"\u003eID\u003c/var\u003e\",\n }\n\n### Drive API v2\n\n {\n 'key': 'additionalID',\n 'value': '\u003cvar translate=\"no\"\u003eID\u003c/var\u003e',\n 'visibility': 'PRIVATE'\n }\n\nWorking with custom file properties\n-----------------------------------\n\nThe section explains how to perform some custom file property-related tasks that\naffect all applications.\n| **Note:** The Google Drive UI doesn't include a built-in way for you to edit custom properties.\n\n### Add or update custom file properties\n\nTo add or update properties visible to all applications, use the\n[`files.update`](/workspace/drive/api/reference/rest/v3/files/update) method to set the\n`properties` field of the [`files`](/workspace/drive/api/reference/rest/v3/files)\nresource. \n\n PATCH https://www.googleapis.com/drive/v3/files/\u003cvar translate=\"no\"\u003eFILE_ID\u003c/var\u003e\n\n```text\n{\n \"properties\": {\n \"name\": \"wrench\",\n \"mass\": \"1.3kg\",\n \"count\": \"3\"\n }\n}\n```\n\nYou can also add a custom property to a file using the advanced\nDrive service in Google Apps Script. For more information, see\n[Adding custom\nproperties](/apps-script/advanced/drive#adding_custom_properties).\n\n### Get or list custom file properties\n\nTo view properties visible to all applications, use the\n[`files.get`](/workspace/drive/api/reference/rest/v3/files/get) method to retrieve the\ncustom file properties for the file. \n\n GET https://www.googleapis.com/drive/v3/files/\u003cvar translate=\"no\"\u003eFILE_ID\u003c/var\u003e?fields=properties\n\nThe response consists of a `properties` object that contains a collection of\nkey-value pairs. \n\n```text\n{\n \"properties\": {\n \"name\": \"wrench\",\n \"mass\": \"1.3kg\",\n \"count\": \"3\"\n }\n}\n```\n\n### Delete custom file properties\n\nTo delete property values visible to all applications, use the\n[`files.update`](/workspace/drive/api/reference/rest/v3/files/update) method to set the\n`properties` field of the [`files`](/workspace/drive/api/reference/rest/v3/files)\nresource to null. \n\n PATCH https://www.googleapis.com/drive/v3/files/\u003cvar translate=\"no\"\u003eFILE_ID\u003c/var\u003e\n\n```text\n{\n \"name\": null\n}\n```\n\nTo view the change, call the\n[`files.get`](/workspace/drive/api/reference/rest/v3/files/get) method to retrieve the\n`properties` object for the file. \n\n```text\n{\n \"properties\": {\n \"mass\": \"1.3kg\",\n \"count\": \"3\"\n }\n}\n```\n\nLimits of custom file properties\n--------------------------------\n\nCustom properties have the following limits:\n\n- Maximum of 100 custom properties per file, totaled from all sources.\n- Maximum of 30 public properties per file, totaled from all sources.\n- Maximum of 30 private properties per file from any one application.\n- Maximum of 124 bytes per property string (including both key and value) in UTF-8 encoding. For example, a property with a key that's 10 characters long can only have 114 characters in the value. Similarly, a property that requires 100 characters for the value can use up to 24 characters for the key.\n\nFor more information, see the [`files`](/workspace/drive/api/reference/rest/v3/files)\nresource. For Drive API v2, see the\n[`properties`](/workspace/drive/api/v2/reference/properties) resource.\n\nAccess private custom file properties\n-------------------------------------\n\nYou can only retrieve private properties using the `appProperties` field through\nan authenticated request that uses an access token obtained with an OAuth 2.0\nclient ID. You cannot use an API key to retrieve private properties."]]
