개발자 메타데이터 기능을 사용하면 스프레드시트의 다양한 항목 및 위치와 메타데이터를 연결할 수 있습니다. 그런 다음 이 메타데이터를 쿼리하고 이를 사용하여 연결된 객체를 찾을 수 있습니다.
메타데이터를 행, 열, 시트 또는 스프레드시트와 연결할 수 있습니다.
개발자 메타데이터를 사용하면 다음과 같은 작업을 실행할 수 있습니다.
스프레드시트의 다양한 항목 및 위치와 임의의 데이터 연결: 예를 들어
totals을 D열과 연결하거나responseId = 1234을 7행과 연결합니다.특정 메타데이터 키 또는 속성과 연결된 모든 위치와 데이터 찾기: 예를 들어 D 열과 연결된
totals키가 지정되거나responseId이 지정된 경우responseId메타데이터와 연결된 메타데이터 값이 있는 모든 행을 반환합니다.특정 항목 또는 위치와 연결된 모든 데이터 찾기: 예를 들어 D열이 주어지면 해당 위치와 연결된 모든 메타데이터를 반환합니다.
연결된 메타데이터를 지정하여 위치의 값 가져오기: 예를 들어
totals가 주어지면 연결된 열 또는 행에 포함된 값의 표현을 반환하고summary가 주어지면 연결된 시트 리소스의 표현을 반환합니다.연결된 메타데이터를 지정하여 위치의 값 업데이트: 예를 들어 A1 표기법을 통해 행의 값을 업데이트하는 대신 메타데이터 ID를 표시하여 값을 업데이트합니다.
메타데이터 읽기 및 쓰기
spreadsheets.developerMetadata 리소스는 스프레드시트의 위치 또는 객체와 연결된 개발자 메타데이터에 대한 액세스를 제공합니다.
개발자 메타데이터 정보
이 섹션에서는 Sheets API를 사용할 때 고려해야 하는 개발자 메타데이터의 몇 가지 주요 측면을 설명합니다.
태그로 된 메타데이터
개발자 메타데이터의 한 가지 용도는 키와 위치만 사용하여 스프레드시트의 위치를 지정하는 태그입니다. 예를 들어 headerRow를 특정 행과 연결하거나 totals를 시트 내의 특정 열과 연결할 수 있습니다. 태그를 사용하여 스프레드시트의 일부를 서드 파티 도구 또는 데이터베이스의 필드에 의미적으로 바인딩할 수 있으므로 스프레드시트를 변경해도 앱이 중단되지 않습니다.
속성으로 사용되는 메타데이터
키, 위치, 값을 지정하여 만든 메타데이터는 시트의 해당 위치와 연결된 키-값 쌍으로 작동합니다. 예를 들어 다음을 연결할 수 있습니다.
formResponseId = resp123(행 포함)lastUpdated = 1477369882을 열과 연결합니다.
이를 통해 스프레드시트의 특정 영역 또는 데이터와 연결된 맞춤 이름 지정 속성을 저장하고 액세스할 수 있습니다.
프로젝트와 문서에 표시되는 메타데이터
한 개발자 프로젝트가 다른 개발자 프로젝트의 메타데이터를 방해하지 않도록 project 및 document의 두 가지 메타데이터 visibility 설정이 있습니다. Sheets API를 사용하면 프로젝트 메타데이터는 이를 만든 개발자 프로젝트에서만 표시되고 액세스할 수 있습니다. 문서 메타데이터는 문서에 액세스할 수 있는 모든 개발자 프로젝트에서 액세스할 수 있습니다.
공개 상태를 명시적으로 지정하지 않는 쿼리는 요청을 수행하는 개발자 프로젝트의 일치하는 문서 메타데이터와 일치하는 프로젝트 메타데이터를 반환합니다.
고유성
메타데이터 키는 고유하지 않아도 되지만 metadataId는 고유해야 합니다. 메타데이터를 만들고 ID 필드를 지정하지 않으면 API에서 ID를 할당합니다. 이 ID는 메타데이터를 식별하는 데 사용할 수 있으며, 키와 기타 속성은 메타데이터 집합을 식별하는 데 사용할 수 있습니다.
메타데이터 만들기
메타데이터를 만들려면 batchUpdate 메서드를 사용하고 metadataKey, location, visibility가 포함된 createDeveloperMetadataRequest를 제공합니다. 선택적으로 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"
}
}
}
]
}단일 메타데이터 항목 읽기
단일 고유 개발자 메타데이터를 가져오려면 메타데이터가 포함된 spreadsheetId와 개발자 메타데이터의 고유 metadataId를 지정하여 spreadsheets.developerMetadata.get 메서드를 사용합니다.
요청
이 예에서는 요청에 스프레드시트 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 메서드를 사용합니다. 'ID가 metadataId인 개발자 메타데이터가 없습니다.404: Not Found
요청
{
"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개인 스프레드시트에는 최대 120,000자의 개발자 메타데이터가 포함될 수 있습니다.
developerMetadata 객체의 키 및 값 속성에 있는 각 문자는 이 한도에 포함됩니다.