개발자 메타데이터 기능을 사용하면 스프레드시트의 다양한 항목 및 위치와 메타데이터를 연결할 수 있습니다. 그런 다음 이 메타데이터를 쿼리하고 이를 사용하여 연결된 객체를 찾을 수 있습니다.
메타데이터를 행, 열, 시트 또는 스프레드시트와 연결할 수 있습니다.
개발자 메타데이터를 사용하면 다음과 같은 작업을 실행할 수 있습니다.
임의의 데이터를 스프레드시트의 다양한 항목 및 위치와 연결: 예를 들어
totals를 D열과 연결하거나responseId = 1234를 7번 행과 연결합니다.특정 메타데이터 키 또는 속성과 연결된 모든 위치 및 데이터 찾기: 예를 들어 D열과 연결된 키
totals가 주어지거나responseId가 주어지면responseId메타데이터와 연결된 모든 행과 연결된 메타데이터 값을 반환합니다.특정 항목 또는 위치와 연결된 모든 데이터 찾기: 예를 들어 D열이 주어지면 해당 위치와 연결된 모든 메타데이터를 반환합니다.
연결된 메타데이터를 지정하여 위치의 값 검색: 예를 들어
totals가 주어지면 연결된 열 또는 행에 포함된 값의 표현을 반환하거나summary가 주어지면 연결된 시트 리소스의 표현을 반환합니다.연결된 메타데이터를 지정하여 위치의 값 업데이트: 예를 들어 A1 표기법을 통해 행의 값을 업데이트하는 대신 메타데이터 ID를 표시하여 값을 업데이트합니다.
메타데이터 읽기 및 쓰기
spreadsheets.developerMetadata 리소스를 사용하면 스프레드시트의 위치 또는 객체와 연결된 개발자 메타데이터에 액세스할 수 있습니다.
개발자 메타데이터 정보
이 섹션에서는 Sheets API를 사용할 때 고려해야 하는 개발자 메타데이터의 몇 가지 주요 측면을 설명합니다.
태그로 사용되는 메타데이터
개발자 메타데이터의 한 가지 용도는 키와 위치만 사용하여 스프레드시트에서 위치의 이름을 지정하는 태그입니다. 예를 들어 headerRow를 특정 행에 연결하거나 totals를 시트 내 특정 열에 연결할 수 있습니다. 태그를 사용하여 스프레드시트의 일부를 서드 파티 도구 또는 데이터베이스의 필드에 의미론적으로 바인딩할 수 있으므로 스프레드시트를 변경해도 앱이 손상되지 않습니다.
속성으로서의 메타데이터
키, 위치, 값을 지정하여 만든 메타데이터는 시트의 해당 위치와 연결된 키-값 쌍 역할을 합니다. 예를 들어 다음을 연결할 수 있습니다.
- 행이 있는
formResponseId = resp123 lastUpdated = 1477369882열을 사용합니다.
이를 통해 스프레드시트의 특정 영역 또는 데이터와 연결된 맞춤 이름 속성을 저장하고 액세스할 수 있습니다.
프로젝트 메타데이터와 문서에 표시되는 메타데이터 비교
한 개발자 프로젝트가 다른 프로젝트의 메타데이터를 방해하지 못하도록 하기 위해 visibility 메타데이터 설정에는 project 및 document의 두 가지가 있습니다. Sheets API를 사용하면 프로젝트 메타데이터를 생성한 개발자 프로젝트에서만 볼 수 있고 액세스할 수 있습니다. 문서 메타데이터는 문서에 액세스할 수 있는 모든 개발자 프로젝트에서 액세스할 수 있습니다.
공개 상태를 명시적으로 지정하지 않는 쿼리는 일치하는 문서 메타데이터와 요청하는 개발자 프로젝트의 일치하는 프로젝트 메타데이터를 반환합니다.
고유성
메타데이터 키는 고유하지 않아도 되지만 metadataId는 고유해야 합니다. 메타데이터를 만들고 ID 필드를 지정하지 않으면 API에서 ID를 할당합니다. 이 ID는 메타데이터를 식별하는 데 사용할 수 있으며 키와 기타 속성은 메타데이터 집합을 식별하는 데 사용할 수 있습니다.
메타데이터 만들기
메타데이터를 만들려면 batchUpdate 메서드를 사용하고 createDeveloperMetadataRequest에 metadataKey, location, visibility를 제공합니다. 선택적으로 metadataValue 또는 명시적 metadataId를 지정할 수 있습니다.
이미 사용 중인 ID를 지정하면 요청이 실패합니다. ID를 제공하지 않으면 API에서 ID를 할당합니다.
예 보기
이 예에서는 요청에 키, 값, 행을 제공합니다. 응답은 이러한 개발자 메타데이터 값과 할당된 메타데이터 ID를 반환합니다.
요청
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}응답
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
}
}
]
}단일 메타데이터 항목 읽기
고유한 단일 개발자 메타데이터를 검색하려면 spreadsheets.developerMetadata.get 메서드를 사용하여 메타데이터와 개발자 메타데이터의 고유한 metadataId가 포함된 spreadsheetId를 지정합니다.
예 보기
요청
이 예에서는 요청에 스프레드시트 ID와 메타데이터 ID를 제공합니다. 응답은 메타데이터 ID의 개발자 메타데이터 값을 반환합니다.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
응답
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}여러 메타데이터 항목 읽기
개발자 메타데이터의 여러 항목을 검색하려면 spreadsheets.developerMetadata.search 메서드를 사용하세요. 키, 값, 위치, 공개 상태와 같은 속성 조합에서 기존 메타데이터와 일치하는 DataFilter를 지정해야 합니다.
예 보기
이 예에서는 요청에 여러 메타데이터 ID를 제공합니다. 응답은 각 메타데이터 ID의 개발자 메타데이터 값을 반환합니다.
요청
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}응답
{
"matchedDeveloperMetadata": [
{
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Revenue",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
},
{
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}메타데이터 업데이트
개발자 메타데이터를 업데이트하려면 spreadsheets.batchUpdate 메서드를 사용하고 UpdateDeveloperMetadataRequest를 제공합니다.
업데이트할 메타데이터를 타겟팅하는 DataFilter, 새 값이 포함된 DeveloperMetadata 객체, 업데이트할 필드를 설명하는 필드 마스크를 지정해야 합니다.
예 보기
이 예에서는 요청에 메타데이터 ID, 시트 ID, 새 메타데이터 키를 제공합니다. 응답은 이러한 개발자 메타데이터 값과 업데이트된 메타데이터 키를 반환합니다.
요청
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}응답
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}메타데이터 삭제
개발자 메타데이터를 삭제하려면 batchUpdate 메서드를 사용하고 DeleteDeveloperMetadataRequest를 제공합니다.
삭제하려는 메타데이터를 선택하려면 DataFilter를 지정해야 합니다.
예 보기
이 예에서는 요청에 메타데이터 ID를 제공합니다. 응답은 메타데이터 ID의 개발자 메타데이터 값을 반환합니다.
개발자 메타데이터가 삭제되었는지 확인하려면 삭제된 메타데이터 ID를 지정하여 spreadsheets.developerMetadata.get 메서드를 사용합니다. 404: Not Found HTTP 상태 코드 응답과 함께 'ID가 metadataId인 개발자 메타데이터가 없습니다.
요청
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}응답
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}메타데이터와 연결된 값 읽기 및 쓰기
연결된 개발자 메타데이터와 업데이트하려는 값을 지정하여 행과 열의 셀 값을 검색하고 업데이트할 수도 있습니다. 이렇게 하려면 일치하는 DataFilter와 함께 아래의 적절한 메서드를 사용합니다.
메타데이터별 셀 값 가져오기
메타데이터별로 셀 값을 가져오려면 spreadsheets.values.batchGetByDataFilter 메서드를 사용하세요. 스프레드시트 ID와 메타데이터와 일치하는 하나 이상의 데이터 필터를 지정해야 합니다.
예 보기
이 예에서는 요청에 메타데이터 ID를 제공합니다. 응답은 메타데이터 ID의 행 셀 값 (모델 번호, 월별 판매량)을 반환합니다.
요청
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}응답
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}메타데이터로 스프레드시트 가져오기
스프레드시트를 검색할 때 spreadsheets.getByDataFilter 메서드를 사용하여 데이터의 하위 집합을 반환할 수 있습니다. 스프레드시트 ID와 메타데이터와 일치하는 하나 이상의 데이터 필터를 지정해야 합니다.
이 요청은 지정된 데이터 필터와 일치하는 메타데이터 목록에 따라 메타데이터가 포함된 시트, 그리드 데이터, 기타 객체 리소스가 반환되는 것을 제외하고 일반 '스프레드시트 GET' 요청으로 작동합니다. includeGridData가 true로 설정되면 지정된 그리드 범위와 교차하는 그리드 데이터도 시트에 반환됩니다.
예 보기
이 예에서는 메타데이터 ID를 제공하고 요청에서 includeGridData를 false로 설정합니다. 응답은 스프레드시트 속성과 시트 속성을 모두 반환합니다.
요청
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}응답
{ "spreadsheetId": spreadsheetId, "properties": { "title": "Sales Sheet", "locale": "en_US", "autoRecalc": "ON_CHANGE", "timeZone": "America/Los_Angeles", "defaultFormat": { "backgroundColor": { "red": 1, "green": 1, "blue": 1 }, "padding": { "top": 2, "right": 3, "bottom": 2, "left": 3 }, "verticalAlignment": "BOTTOM", "wrapStrategy": "OVERFLOW_CELL", "textFormat": { "foregroundColor": {}, "fontFamily": "arial,sans,sans-serif", "fontSize": 10, "bold": false, "italic": false, "strikethrough": false, "underline": false, "foregroundColorStyle": { "rgbColor": {} } }, "backgroundColorStyle": { "rgbColor": { "red": 1, "green": 1, "blue": 1 } } }, "spreadsheetTheme": { "primaryFontFamily": "Arial", "themeColors": [ { "colorType": "TEXT", "color": { "rgbColor": {} } }, { "colorType": "BACKGROUND", "color": { "rgbColor": { "red": 1, "green": 1, "blue": 1 } } }, { "colorType": "ACCENT1", "color": { "rgbColor": { "red": 0.25882354, "green": 0.52156866, "blue": 0.95686275 } } }, { "colorType": "ACCENT2", "color": { "rgbColor": { "red": 0.91764706, "green": 0.2627451, "blue": 0.20784314 } } }, { "colorType": "ACCENT3", "color": { "rgbColor": { "red": 0.9843137, "green": 0.7372549, "blue": 0.015686275 } } }, { "colorType": "ACCENT4", "color": { "rgbColor": { "red": 0.20392157, "green": 0.65882355, "blue": 0.3254902 } } }, { "colorType": "ACCENT5", "color": { "rgbColor": { "red": 1, "green": 0.42745098, "blue": 0.003921569 } } }, { "colorType": "ACCENT6", "color": { "rgbColor": { "red": 0.27450982, "green": 0.7411765, "blue": 0.7764706 } } }, { "colorType": "LINK", "color": { "rgbColor": { "red": 0.06666667, "green": 0.33333334, "blue": 0.8 } } } ] } }, "sheets": [ { "properties": { "sheetId": sheetId, "title": "Sheet7", "index": 7, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26 } } } ], "spreadsheetUrl": spreadsheetUrl }
메타데이터별로 값 업데이트
특정 메타데이터와 일치하는 셀 값을 업데이트하려면 spreadsheets.values.batchUpdateByDataFilter 메서드를 사용하세요. 스프레드시트 ID, valueInputOption, 메타데이터와 일치하는 DataFilterValueRange를 하나 이상 지정해야 합니다.
예 보기
이 예에서는 요청에 메타데이터 ID와 업데이트된 행 값을 제공합니다. 응답에는 업데이트된 속성과 메타데이터 ID의 데이터가 모두 반환됩니다.
요청
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}응답
{
"spreadsheetId": spreadsheetId,
"totalUpdatedRows": 1,
"totalUpdatedColumns": 2,
"totalUpdatedCells": 2,
"totalUpdatedSheets": 1,
"responses": [
{
"updatedRange": "Sheet7!A7:B7",
"updatedRows": 1,
"updatedColumns": 2,
"updatedCells": 2,
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"updatedData": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
}
]
}메타데이터별로 값 지우기
특정 메타데이터와 일치하는 셀 값을 지우려면 spreadsheets.values.batchClearByDataFilter 메서드를 사용하세요. 삭제할 메타데이터를 선택하려면 데이터 필터를 지정해야 합니다.
예 보기
요청
이 예에서는 요청에 메타데이터 ID를 제공합니다. 응답에는 스프레드시트 ID와 삭제된 범위가 반환됩니다.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}응답
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}메타데이터 스토리지 한도
스프레드시트에 저장할 수 있는 총 메타데이터 양에는 제한이 있습니다. 이 제한은 글자 수로 측정되며 다음 두 가지 구성요소로 구성됩니다.
| 항목 | 스토리지 한도 할당 |
|---|---|
| 스프레드시트 | 30,000자 |
| 스프레드시트 내의 각 시트 | 30,000자 |
스프레드시트에는 최대 30,000자(영문 기준)를 저장할 수 있습니다. 또한 스프레드시트 내 각 시트에 30,000자 (시트 1의 경우 30,000자, 시트 2의 경우 30,000자 등)를 저장할 수 있습니다. 따라서 페이지가 3개인 스프레드시트에는 최대 12만 자의 개발자 메타데이터가 포함될 수 있습니다.
developerMetadata 객체의 키 및 값 속성의 각 문자가 이 한도에 포함됩니다.