필드 마스크 사용

필드 마스크는 API 호출자가 요청이 처리해야 하는 필드를 나열하는 방법입니다. 반환할 수 있습니다. FieldMask API를 사용하면 불필요한 작업을 방지하고 성능을 개선할 수 있습니다. 필드 마스크 는 Google Sheets API의 읽기 및 업데이트 메서드에 모두 사용됩니다.

필드 마스크를 사용하여 읽기

스프레드시트는 클 수 있으며, 대부분의 경우 스프레드시트의 모든 부분이 Spreadsheet 읽기 요청에서 반환한 리소스입니다. 반환되는 결과를 fields URL 매개변수를 사용한 Sheets API 응답 최고의 성능 실적, 필요한 필드만 명시적으로 나열 답장에 추가해 주세요.

필드 매개변수의 형식은 FieldMask의 JSON 인코딩입니다. 간단히 말하면, 서로 다른 여러 필드는 쉼표로 구분되며 하위 필드는 점으로 구분됩니다. 필드 이름은 camelCase 또는 separated_by_underscores됩니다. 편의상 동일한 필드의 여러 하위 필드가 유형은 괄호 안에 나열할 수 있습니다.

다음 spreadsheets.get 요청 예시에서는 sheets.properties(sheetId,title,sheetType,gridProperties)의 필드 마스크를 사용하여 시트 ID, 제목, 파일 이름만 SheetType 및 GridProperties (이 중) SheetProperties 개체에 대한 작업을 처리할 수 있습니다.

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)

이 메서드 호출에 대한 응답은 Spreadsheet 필드 마스크에 요청된 구성요소가 포함된 객체입니다. 참고: sheetType=OBJECT에 gridProperties가 포함되지 않음:

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 25
        }
      }
    },
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "OBJECT"
      }
    }
  ]
}

필드 마스크를 사용한 업데이트

객체의 특정 필드만 업데이트하면서 다른 필드는 변경되지 않았습니다. 내부의 업데이트 요청 spreadsheets.batchUpdate 작업은 필드 마스크를 사용하여 변경 중인 필드를 API에 알립니다. 이 업데이트 요청은 필드 마스크에 지정되지 않은 모든 필드를 무시하므로 현재 값을 그대로 둡니다

업데이트된 메시지에서 필드를 지정하지 않고 필드를 설정 해제할 수도 있지만 마스크에 필드를 추가합니다 이렇게 하면 이전에 필드의 값이 무엇이든 지워집니다. 있습니다.

업데이트 필드 마스크의 구문은 읽기 필드 마스크와 동일합니다.

다음 예에서는 AddSheetRequest Grid 유형의 새 시트를 추가하고 첫 번째 행을 고정한 다음 새 행에 색상을 지정합니다. 시트의 탭 빨간색:

POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
{
  "spreadsheetId": "SPREADSHEET_ID",
  "replies": [
    {
      "addSheet": {
        "properties": {
          "sheetId": SHEET_ID,
          "title": "TITLE",
          "index": 6,
          "sheetType": "GRID",
          "gridProperties": {
            "rowCount": 1000,
            "columnCount": 26,
            "frozenRowCount": 1
          },
          "tabColor": {
            "red": 0.003921569
          },
          "tabColorStyle": {
            "rgbColor": {
              "red": 0.003921569
            }
          }
        }
      }
    }
  ]
}