메타데이터 기능을 사용하면 스프레드시트의 다양한 항목 및 위치와 메타데이터를 연결할 수 있습니다. 그런 다음 이 메타데이터를 쿼리하고 이를 사용하여 연결된 객체를 찾을 수 있습니다.
메타데이터를 행, 열, 시트 또는 스프레드시트와 연결할 수 있습니다.
메타데이터 정보
다음은 Sheets API를 사용할 때 고려해야 할 메타데이터의 몇 가지 주요 측면을 설명합니다.
태그로서의 메타데이터: 개발자 메타데이터의 한 가지 용도는 키와 위치만 사용하여 스프레드시트의 위치를 지정하는 태그입니다. 예를 들어
headerRow를 특정 행과 연결하거나totals를 시트 내의 특정 열과 연결할 수 있습니다. 태그를 사용하여 스프레드시트의 일부를 서드 파티 도구 또는 데이터베이스의 필드에 의미적으로 바인딩할 수 있으므로 스프레드시트 변경으로 인해 앱이 중단되지 않습니다.속성으로서의 메타데이터: 키, 위치, 및 값을 지정하여 만든 메타데이터는 시트의 해당 위치와 연결된 키-값 쌍 역할을 합니다. 예를 들어 다음과 같은 항목을 연결할 수 있습니다.
formResponseId = resp123을 행과 연결lastUpdated = 1477369882를 열과 연결
이를 통해 스프레드시트의 특정 영역 또는 데이터와 연결된 맞춤 이름 지정 속성을 저장하고 액세스할 수 있습니다.
프로젝트 표시 메타데이터와 문서 표시 메타데이터: 한 개발자 프로젝트가 다른 개발자 프로젝트의 메타데이터를 방해하지 않도록 두 가지 메타데이터
visibility설정(project및document)이 있습니다. Sheets API를 사용하면project메타데이터는 이를 만든 Google Cloud 프로젝트에서만 표시되고 액세스할 수 있습니다.document메타데이터는 문서에 액세스할 수 있는 모든 Google Cloud 프로젝트에서 액세스할 수 있습니다.visibility를 명시적으로 지정하지 않는 쿼리는 요청을 하는 Google Cloud 프로젝트에 대해 일치하는document메타데이터와 일치하는project메타데이터를 반환합니다.고유성: 메타데이터 키는 고유할 필요는 없지만
metadataId는 고유해야 합니다. 메타데이터를 만들고 ID 필드를 지정하지 않은 상태로 두면 API에서 ID를 할당합니다. 이 ID는 메타데이터를 식별하는 데 사용할 수 있으며 키 및 기타 속성은 메타데이터 집합을 식별하는 데 사용할 수 있습니다.API 요청을 통해 메타데이터 반환:
DataFilter객체는 API 요청에서 선택하거나 반환할 데이터를 설명하는 API 호출의 일부입니다.단일
DataFilter객체는 데이터를 찾는 데 사용할 필터 기준 유형을 하나만 지정할 수 있습니다.developerMetadataLookup: 기준과 일치하는 지정된 개발자 메타데이터와 연결된 데이터를 선택합니다.a1Range: 지정된 A1 표기법 범위와 일치하는 데이터를 선택합니다. 예를 들어Sheet1!A1:B10입니다.gridRange: 0부터 시작하는 색인을 사용하여 지정된 그리드 범위와 일치하는 데이터를 선택합니다. 예를 들어Sheet1!A3:B4 == sheetId: 123456, startRowIndex: 2, endRowIndex: 4, startColumnIndex: 0, endColumnIndex: 2입니다.
여러 위치 또는 기준에 걸쳐 필터링하려면 단일 API 요청에서 여러
DataFilter객체를 사용하면 됩니다.DataFilter객체의 배열 또는 목록을spreadsheets.values.batchGetByDataFilter메서드와 같은 일괄 요청에 제공합니다. 요청의 데이터 필터와 일치하는 범위는 반환되거나 수정됩니다.자세한 내용은 메타데이터와 연결된 값 읽기 및 쓰기를 참고하세요.
사용 사례
다음은 메타데이터 관리를 위한 몇 가지 사용 사례입니다.
스프레드시트 의 다양한 항목 및 위치와 임의의 데이터 연결: 예를 들어 열 D와
totals를 연결하거나 행 7과responseId = 1234를 연결합니다.특정 메타데이터 키 또는 속성과 연결된 모든 위치 및 데이터 찾기: 예를 들어 열 D와 연결된 키
totals또는responseId가 지정된 경우responseId메타데이터와 연결된 메타데이터 값이 있는 모든 행을 반환합니다.특정 항목 또는 위치와 연결된 모든 데이터 찾기: 예를 들어 열 D가 지정된 경우 해당 위치와 연결된 모든 메타데이터를 반환합니다.
연결된 메타데이터를 지정하여 위치의 값 검색: 예를 들어
totals가 지정된 경우 연결된 열 또는 행에 포함된 값의 표현을 반환하거나summary가 지정된 경우 연결된 시트 리소스의 표현을 반환합니다.연결된 메타데이터를 지정하여 위치의 값 업데이트: 예를 들어 A1 표기법을 통해 행의 값을 업데이트하는 대신 메101}타데이터 ID를 표시하여 값을 업데이트합니다.
메타데이터 읽기 및 쓰기
spreadsheets.developerMetadata
리소스는 스프레드시트의 위치 또는 객체와 연결된 메타데이터에 대한 액세스 권한을 제공합니다. 개발자 메타데이터를 사용하여 스프레드시트의 다양한 부분과 임의의 데이터를 연결할 수 있습니다. 스프레드시트가 수정될 때 메타데이터는 해당 위치에 연결된 상태로 유지됩니다.
메타데이터 만들기
메타데이터를 만들려면
batchUpdate
메서드를
spreadsheets 리소스에서 사용하고
spreadsheets.developerMetadata 리소스의 metadataKey, location, visibility 값을 사용하여
CreateDeveloperMetadataRequest
를 제공합니다. 선택적으로 metadataValue 또는 명시적 metadataId를 지정할 수 있습니다.
이미 사용 중인 ID를 지정하면 요청이 실패합니다. ID를 제공하지 않으면 API에서 ID를 할당합니다.
이 예에서는 요청에 키, 값, 행을 제공합니다. 응답은 이러한 개발자 메타데이터 값과 할당된 메타데이터 ID를 반환합니다.
요청
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}응답
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
}
}
]
}단일 메타데이터 항목 읽기
단일 고유 개발자 메타데이터를 검색하려면
spreadsheets.developerMetadata.get
메서드를 사용하고 메타데이터가 포함된 spreadsheetId와 개발자
메타데이터의 고유 metadataId를 지정합니다.
요청
이 예에서는 요청에 스프레드시트 ID와 메타데이터 ID를 제공합니다. 응답은 메타데이터 ID의 개발자 메타데이터 값을 반환합니다.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/developerMetadata/METADATA_ID
응답
{
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}여러 메타데이터 항목 읽기
여러 개발자 메타데이터 항목을 검색하려면
spreadsheets.developerMetadata.search
메서드를 사용합니다. 키, 값,
위치, 공개 상태와 같은 속성의 조합에서 기존 메타데이터와 일치하는
DataFilter를 지정해야 합니다.
이 예에서는 요청에 여러 메타데이터 ID를 제공합니다. 응답은 각 메타데이터 ID의 개발자 메타데이터 값을 반환합니다.
요청
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}응답
{
"matchedDeveloperMetadata": [
{
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Revenue",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
},
{
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}메타데이터 업데이트
개발자 메타데이터를 업데이트하려면
spreadsheets.batchUpdate
메서드를 사용하고
UpdateDeveloperMetadataRequest를 제공합니다.
업데이트할 메타데이터를 타겟팅하는
DataFilter, 새 값이 있는
spreadsheets.developerMetadata
리소스, 업데이트할 필드를 설명하는 필드
마스크를 지정해야 합니다.
이 예에서는 요청에 메타데이터 ID, 시트 ID, 새 메타데이터 키를 제공합니다. 응답은 이러한 개발자 메타데이터 값과 업데이트된 메타데이터 키를 반환합니다.
요청
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"developerMetadata": {
"location": {
"sheetId": SHEET_ID
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}응답
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}메타데이터 삭제
개발자 메타데이터를 삭제하려면
batchUpdate
메서드를 사용하고
DeleteDeveloperMetadataRequest를 제공합니다.
삭제할
메타데이터를 선택하려면
DataFilter를 지정해야 합니다.
이 예에서는 요청에 메타데이터 ID를 제공합니다. 응답은 메타데이터 ID의 개발자 메타데이터 값을 반환합니다.
개발자 메타데이터가 삭제되었는지 확인하려면 spreadsheets.developerMetadata.get
메서드를 사용하여 삭제된 메타데이터 ID를 지정합니다. 'METADATA_ID ID가 있는 개발자 메타데이터가 없습니다'라는 메시지와 함께 404: Not Found HTTP 상태 코드 응답이 표시됩니다.
요청
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
}
}
]
}응답
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}메타데이터와 연결된 값 읽기 및 쓰기
연결된 개발자 메타데이터와 업데이트할 값을 지정하여 행과 열의 셀 값을 검색하고 업데이트할 수도 있습니다. 이렇게 하려면
일치하는
DataFilter와 함께 다음 메서드 중 하나를 사용합니다.
메타데이터로 셀 값 가져오기
메타데이터로 셀 값을 가져오려면
spreadsheets.values.batchGetByDataFilter
메서드를 사용합니다. 스프레드시트 ID와 메타데이터와 일치하는 데이터 필터를 하나 이상 지정해야 합니다.
이 예에서는 요청에 메타데이터 ID를 제공합니다. 응답은 메타데이터 ID의 행 셀 값 (모델 번호, 월별 판매량)을 반환합니다.
요청
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"majorDimension": "ROWS"
}응답
{
"spreadsheetId": SPREADSHEET_ID,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}메타데이터로 스프레드시트 가져오기
스프레드시트를 검색할 때
spreadsheets.getByDataFilter
메서드를 사용하여 데이터의 하위 집합을 반환할 수 있습니다. 스프레드시트 ID와 메타데이터와 일치하는 데이터 필터를 하나 이상 지정해야 합니다.
이 요청은 지정된 데이터 필터와 일치하는 메타데이터 목록이 메타데이터가 있는 시트, 그리드 데이터, 기타 객체 리소스가 반환되는지 여부를 결정한다는 점을 제외하면 일반적인 '스프레드시트 GET' 요청으로 작동합니다.
includeGridData
가 true로 설정된 경우 지정된 그리드 범위와 교차하는 그리드 데이터도
시트에 대해 반환됩니다. 요청에 필드
마스크가 설정된 경우 includeGridData 필드는 무시됩니다.
이 예에서는 요청에 메타데이터 ID를 제공하고 includeGridData를 false로 설정합니다. 응답은 스프레드시트와 시트 속성을 모두 반환합니다.
요청
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"includeGridData": false
}응답
{ "spreadsheetId": SPREADSHEET_ID, "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": SHEET_ID, "title": "Sheet7", "index": 7, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26 } } } ], "spreadsheetUrl": SPREADSHEET_URL }
메타데이터로 값 업데이트
특정 메타데이터와 일치하는 셀 값을 업데이트하려면
spreadsheets.values.batchUpdateByDataFilter
메서드를 사용합니다. 스프레드시트 ID,
valueInputOption,
메타데이터와 일치하는
DataFilterValueRange
값을 하나 이상 지정해야 합니다.
이 예에서는 요청에 메타데이터 ID와 업데이트된 행 값을 제공합니다. 응답은 메타데이터 ID의 업데이트된 속성과 데이터를 모두 반환합니다.
요청
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}응답
{
"spreadsheetId": SPREADSHEET_ID,
"totalUpdatedRows": 1,
"totalUpdatedColumns": 2,
"totalUpdatedCells": 2,
"totalUpdatedSheets": 1,
"responses": [
{
"updatedRange": "Sheet7!A7:B7",
"updatedRows": 1,
"updatedColumns": 2,
"updatedCells": 2,
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"updatedData": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
}
]
}메타데이터로 값 지우기
특정 메타데이터와 일치하는 셀 값을 지우려면
spreadsheets.values.batchClearByDataFilter
메서드를 사용합니다. 지울 메타데이터를 선택하려면 데이터 필터를 지정해야 합니다.
요청
이 예에서는 요청에 메타데이터 ID를 제공합니다. 응답은 스프레드시트 ID와 지워진 범위를 반환합니다.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}응답
{
"spreadsheetId": SPREADSHEET_ID,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}메타데이터 스토리지 한도
스프레드시트에 저장할 수 있는 총 메타데이터 양에는 제한이 있습니다. 이 한도는 문자 수로 측정되며 두 가지 구성요소로 구성됩니다.
| 항목 | 스토리지 한도 할당 |
|---|---|
| 스프레드시트 | 30,000자(영문 기준) |
| 스프레드시트 내의 각 시트 | 30,000자(영문 기준) |
스프레드시트에 최대 30,000자(영문 기준)를 저장할 수 있습니다. 또한 스프레드시트 내의 각 시트에 30,000자(영문 기준)를 저장할 수 있습니다(시트 1에 30,000자(영문 기준), 시트 2에 30,000자(영문 기준) 등). 따라서 시트가 3개인 스프레드시트에는 최대 120,000자(영문 기준)의 메타데이터가 포함될 수 있습니다.
spreadsheets.developerMetadata
리소스의 metadataKey 및 metadataValue 필드의 각 문자는 이 한도에 포함됩니다.