개발자 메타데이터 읽기 및 쓰기

개발자 메타데이터 기능을 사용하면 메타데이터를 스프레드시트의 다양한 항목 및 위치와 연결할 수 있습니다. 그런 다음 이 메타데이터를 쿼리하고 연결된 객체를 찾는 데 사용할 수 있습니다.

메타데이터를 행, 열, 시트 또는 스프레드시트에 연결할 수 있습니다.

개발자 메타데이터를 사용하면 다음과 같은 작업을 수행할 수 있습니다.

• 임의의 데이터를 스프레드시트의 다양한 항목 및 위치와 연결. 예를 들어 totals을 D열과 연결하거나 responseId = 1234을 행 7과 연결합니다.

• 특정 메타데이터 키 또는 속성과 연결된 모든 위치와 데이터 찾기 - 예를 들어 D열과 연결되었거나 responseId가 지정된 totals 키가 제공되면 responseId 메타데이터와 연결된 메타데이터 값이 있는 모든 행을 반환합니다.

• 특정 항목 또는 위치와 연결된 모든 데이터 찾기 - 예를 들어 주어진 열 D는 해당 위치와 연결된 모든 메타데이터를 반환합니다.

• 연결된 메타데이터를 지정하여 특정 위치의 값을 가져옵니다. 예를 들어 totals가 연결된 열 또는 행에 포함된 값의 표현을 반환하거나 summary가 연결된 시트 리소스의 표현을 반환합니다.

• 연결된 메타데이터를 지정하여 특정 위치의 값 업데이트 - 예를 들어 A1 표기법을 통해 행의 값을 업데이트하는 대신 메타데이터 ID를 표시하여 값을 업데이트합니다.

메타데이터 읽기 및 쓰기

spreadsheets.developerMetadata 리소스는 스프레드시트의 위치 또는 객체에 연결된 개발자 메타데이터에 대한 액세스를 제공합니다.

개발자 메타데이터 정보

이 섹션에서는 Sheets API로 작업할 때 고려해야 하는 개발자 메타데이터의 몇 가지 주요 측면을 설명합니다.

태그로서의 메타데이터

개발자 메타데이터의 한 가지 용도는 키와 위치만 사용하여 스프레드시트에서 위치 이름을 지정하는 태그입니다. 예를 들어 headerRow을 특정 행과 연결하거나 totals을 시트 내의 특정 열과 연결할 수 있습니다. 태그를 사용하여 스프레드시트의 일부를 서드 파티 도구 또는 데이터베이스의 필드에 의미론적으로 결합할 수 있으므로 스프레드시트를 변경해도 앱이 중단되지 않습니다.

속성으로서의 메타데이터

키, 위치, 값을 지정하여 만든 메타데이터는 시트에서 해당 위치와 연결된 키-값 쌍으로 작동합니다. 예를 들어 다음을 연결할 수 있습니다.

• 행 1개가 있는 formResponseId = resp123
• lastUpdated = 1477369882를 열로 바꿉니다.

이를 통해 스프레드시트의 특정 영역 또는 데이터와 연결된 이름이 지정된 커스텀 속성을 저장하고 액세스할 수 있습니다.

프로젝트와 문서에 표시되는 메타데이터 비교

한 개발자 프로젝트가 다른 개발자 프로젝트의 메타데이터를 방해하지 않도록 하기 위해 두 가지 메타데이터 visibility 설정(project 및 document)이 있습니다. Sheets API를 사용하면 프로젝트 메타데이터를 생성한 개발자 프로젝트에서만 프로젝트 메타데이터를 보고 액세스할 수 있습니다. 문서 메타데이터는 문서에 액세스할 수 있는 모든 개발자 프로젝트에서 액세스할 수 있습니다.

공개 상태를 명시적으로 지정하지 않은 쿼리는 일치하는 문서 메타데이터와 요청하는 개발자 프로젝트에 대해 일치하는 프로젝트 메타데이터를 반환합니다.

프로젝트에 표시되는 개발자 메타데이터를 보안 메커니즘으로 사용하거나 보안 비밀을 저장하는 데 사용하지 마세요. 메타데이터는 문서에 대한 보기 액세스 권한이 있는 사용자에게 노출될 수 있습니다.

고유성

메타데이터 키가 고유할 필요는 없지만 metadataId가 고유해야 합니다. 메타데이터를 만들고 ID 필드를 지정하지 않으면 API가 ID 필드를 할당합니다. 이 ID는 메타데이터를 식별하는 데 사용할 수 있고 키와 기타 속성은 메타데이터 세트를 식별하는 데 사용할 수 있습니다.

메타데이터를 만들 때 자체 `metadataId` 를 지정할 수 있지만 Sheets 서비스에서 이를 할당하도록 허용하는 것이 좋습니다.

메타데이터 만들기

메타데이터를 만들려면 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"
        }
      }
    }
  ]
}

단일 메타데이터 항목 읽기

고유한 단일 개발자 메타데이터를 검색하려면 spreadsheets.developerMetadata.get 메서드를 사용하여, 메타데이터가 포함된 spreadsheetId 및 개발자 메타데이터의 고유 metadataId를 지정합니다.

예 보기

요청

이 예에서는 요청에 스프레드시트 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"
  ]
}

메타데이터 저장용량 한도

스프레드시트에 저장할 수 있는 메타데이터의 총량에는 제한이 있습니다. 이 한도는 문자로 측정되며 다음 2가지 요소로 구성됩니다.

상품	저장용량 한도 할당
스프레드시트	30,000자(영문 기준)
스프레드시트 내의 각 시트	30,000자(영문 기준)

스프레드시트에 최대 30,000자(영문 기준)를 저장할 수 있습니다. 또한 스프레드시트 내의 시트당 30,000자 (시트 1의 경우 30,000자, 시트 2의 경우 30,000자 등)를 저장할 수 있습니다. 따라서 세 페이지가 있는 스프레드시트에는 최대 120,000자(영문 기준)의 개발자 메타데이터가 포함될 수 있습니다.

developerMetadata 객체의 키 및 값 속성에 있는 각 문자가 이 한도에 포함됩니다.

이러한 한도는 향후 변경될 수 있습니다.