필터로 데이터 공개 상태 관리

이 문서는 필터를 사용하여 스프레드시트에 표시된 데이터를 정렬하고 필터링하는 방법을 설명합니다.

필터를 사용하면 스프레드시트를 볼 때 표시되는 데이터를 정렬하고 필터링할 수 있습니다. 필터는 스프레드시트의 데이터 값을 변경하지 않습니다. 필터를 사용하여 정보를 일시적으로 숨기거나 정렬할 수 있습니다. 지정된 필터 기준과 일치하는 데이터는 필터가 사용 설정된 동안 표시되지 않습니다. 필터 보기를 사용하면 이름이 지정된 여러 필터를 저장하고 언제든지 전환할 수도 있습니다.

Google Sheets API 요청에서 반환된 데이터를 필터링하려면 DataFilter 객체를 사용합니다. 자세한 내용은 메타데이터 읽기, 쓰기, 검색 을 참고하세요.

필터 사용 사례

다음은 필터의 몇 가지 사용 사례입니다.

  • 특정 열을 기준으로 데이터를 정렬합니다. 예를 들어 사용자 기록을 성 별로 정렬합니다.
  • 특정 조건을 충족하는 데이터를 숨깁니다. 예를 들어 2년 넘게 보관된 모든 기록을 숨깁니다.
  • 특정 값과 일치하는 데이터를 숨깁니다. 예를 들어 상태가 "닫힘"인 모든 문제를 숨깁니다.

기본 필터

스프레드시트의 BasicFilter 객체는 스프레드시트를 보는 모든 사용자에게 적용되는 기본 필터입니다. 스프레드시트에는 시트당 기본 필터가 하나만 있을 수 있습니다. 시트 기본 필터를 지우면 사용 중지할 수 있습니다. 이렇게 하면 스프레드시트에서 필터와 모든 설정이 삭제됩니다. 동일한 필터를 다시 사용 설정하려면 기준을 다시 설정해야 합니다.

기본 필터 관리

기본 필터를 설정하거나 지우려면 적절한 요청 유형과 함께 spreadsheets.batchUpdate 메서드를 사용합니다.

기본 필터를 나열하려면 spreadsheets.get 메서드를 사용하고 fields URL 매개변수를 sheets/basicFilter로 설정합니다. 다음 spreadsheets.get 코드 샘플은 필드 마스크가 있는 Google Sheets URL을 보여줍니다.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets/basicFilter

필터 보기

A FilterView 는 언제든지 사용 중지하거나 사용 설정할 수 있는 이름이 지정된 필터입니다. 시트에는 여러 필터 보기가 저장될 수 있지만 한 번에 하나만 적용할 수 있습니다. 시트 에는 기본 필터와 여러 필터 보기가 모두 포함될 수 있지만 동일한 데이터 범위에 동시에 적용할 수는 없습니다.

필터 보기 사용 사례

다음은 필터 보기의 몇 가지 사용 사례입니다.

  • 데이터를 볼 때 전환하려는 여러 필터가 있습니다.
  • 스프레드시트에 대한 수정 액세스 권한이 없지만 필터를 적용하고 싶습니다. 이 경우 나만 볼 수 있는 임시 필터 보기를 만들 수 있습니다.

  • 스프레드시트를 공유하는 각 사용자가 데이터를 다르게 보기를 원합니다. 스프레드시트 URL에 다음을 spreadsheetId 및 filterViewId 제공하여 적용할 필터 보기를 지정할 수 있습니다. 이렇게 하려면 필터 보기를 만들 때 응답에 반환된 filterViewId를 사용합니다.

    다음 코드 샘플은 필터 보기가 있는 Sheets URL을 보여줍니다.

    https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0&fvid=FILTER_VIEW_ID

필터 보기 관리

필터 보기를 만들거나, 복제하거나, 수정하거나, 삭제하려면 적절한 요청 유형과 함께 spreadsheets.batchUpdate 메서드를 사용합니다.

모든 필터 보기를 나열하려면 spreadsheets.get 메서드를 사용하고 fields URL 매개변수를 sheets/filterViews로 설정합니다. 다음 spreadsheets.get 코드 샘플은 필드 마스크가 있는 Sheets URL을 보여줍니다.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets/filterViews

필터의 JSON 표현

다음 코드 샘플은 FilterView 객체의 JSON 표현을 보여줍니다. BasicFilter 객체는 filterViewId 및 title 필드가 없고 이름이 지정된 범위를 사용할 수 없다는 점을 제외하고는 동일합니다.

{
  "filterViewId": number,
  "title": string,
  "range": {
    object(GridRange)
  },
  "namedRangeId": string,
  "sortSpecs": [
    {
      object(SortSpec)
    }
  ],
  "criteria": {
    string: {
      object(FilterCriteria)
    },
    ...
  }
}

샘플 판매 데이터

이 문서의 나머지 부분에서는 다음 샘플 판매 데이터 표를 참조합니다.

표 1. 샘플 판매 데이터
A B C D E F G
1 항목 카테고리 모델 번호 비용 수량 지역 영업 담당자 배송 날짜
2 휠 W-24 $20.50 4 서부 베스 2016년 3월 1일
3 문 D-01X $15.00 2 남부 아미르 2016년 3월 15일
4 프레임 FR-0B1 $34.00 8 동부 한나 2016년 3월 12일
5 패널 P-034 $6.00 4 북부 데빈 2016년 3월 15일
6 패널 P-052 $11.50 7 동부 에리크 2016년 5월 16일
7 휠 W-24 $20.50 11 남부 셸던 2016년 4월 30일
8 엔진 ENG-0161 $330.00 2 북부 Jessie 2016년 7월 2일

정렬 사양

필터에는 여러 정렬 사양이 있을 수 있습니다. 이러한 사양은 데이터를 정렬하는 방법을 결정하며 지정된 순서로 적용됩니다. SortSpec.dimensionIndex 속성은 정렬을 적용해야 하는 열 색인을 지정합니다.

다음 코드 샘플은 정렬 사양을 보여줍니다.

[
  {
    "dimensionIndex": 3,
    "sortOrder": "ASCENDING"
  },
  {
    "dimensionIndex": 6,
    "sortOrder": "ASCENDING"
  }
]

샘플 판매 데이터에 적용하면 이 사양은 먼저 '수량' 열을 기준으로 정렬한 다음 두 행의 수량이 동일한 경우 '배송 날짜'를 기준으로 정렬합니다.

표 2. 두 열을 기준으로 정렬된 판매 데이터
A B C D E F G
1 항목 카테고리 모델 번호 비용 수량 지역 영업 담당자 배송 날짜
2 문 D-01X $15.00 2 남부 아미르 2016년 3월 15일
3 엔진 ENG-0161 $330.00 2 북부 Jessie 2016년 7월 2일
4 휠 W-24 $20.50 4 서부 베스 2016년 3월 1일
5 패널 P-034 $6.00 4 북부 데빈 2016년 3월 15일
6 패널 P-052 $11.50 7 동부 에리크 2016년 5월 16일
7 프레임 FR-0B1 $34.00 8 동부 한나 2016년 3월 12일
8 휠 W-24 $20.50 11 남부 셸던 2016년 4월 30일

필터 기준

FilterCriteria 객체는 기본 필터 또는 필터 보기에 표시되거나 숨겨지는 스프레드시트 데이터를 결정합니다. 각 기준은 특정 열의 값에 따라 다릅니다. 키가 열 색인이고 값이 기준인 맵으로 필터 기준을 제공합니다.

불리언 condition을 사용하여 지정된 기준의 경우 값을 표시하려면 조건이 true여야 합니다. 조건은 재정의하지 hiddenValues 않습니다. 값이 hiddenValues 아래에 나열되면 값의 모든 일치 항목이 계속 숨겨집니다.

다음 코드 샘플은 필터 기준 맵을 보여줍니다.

{
  0: {
    'hiddenValues': ['Panel']
  },
  6: {
    'condition': {
      'type': 'DATE_BEFORE',
      'values': {
        'userEnteredValue': '4/30/2016'
      }
    }
  }
}

샘플 판매 데이터에 적용하면 이 기준은 '항목 카테고리' 열 값이 '패널'이 아니고 '배송 날짜' 열 값이 '2016년 4월 30일' 이전인 행만 표시합니다.

표 3. 필터 기준을 사용하는 판매 데이터
A B C D E F G
1 항목 카테고리 모델 번호 비용 수량 지역 영업 담당자 배송 날짜
2 휠 W-24 $20.50 4 서부 베스 2016년 3월 1일
3 문 D-01X $15.00 2 남부 아미르 2016년 3월 15일
4 프레임 FR-0B1 $34.00 8 동부 한나 2016년 3월 12일

필터 보기 코드 샘플

다음 코드 샘플은 필터 보기를 만들고, 복제한 다음, 샘플 판매 데이터를 사용하여 복제된 버전을 업데이트하는 방법을 보여줍니다.

자바

sheets/snippets/src/main/java/SheetsFilterViews.java
/*
 * Dependencies (Maven):
 * com.google.apis:google-api-services-sheets:v4-rev20220927-2.0.0
 * com.google.auth:google-auth-library-oauth2-http:1.19.0
 */

import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.*;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.*;

public class SheetsFilterViews {

    public static void main(String... args) {
        filterViews("1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k");
    }

    public static void filterViews(String spreadsheetId) {
        try {
            // Load pre-authorized user credentials from the environment.
            // TODO(developer) - See https://developers.google.com/identity for guides on implementing OAuth2.
            GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
                    .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));

            Sheets service = new Sheets.Builder(
                    GoogleNetHttpTransport.newTrustedTransport(),
                    GsonFactory.getDefaultInstance(),
                    new HttpCredentialsAdapter(credentials))
                    .setApplicationName("Sheets Filter Views Sample")
                    .build();

            // --- Step 1: Add Filter View ---
            GridRange myRange = new GridRange()
                    .setSheetId(0)
                    .setStartRowIndex(0)
                    .setStartColumnIndex(0);

            // Construct Criteria for Column 0 (Hidden Values)
            FilterCriteria criteria0 = new FilterCriteria()
                    .setHiddenValues(Collections.singletonList("Panel"));

            // Construct Criteria for Column 6 (Date Condition)
            ConditionValue dateValue = new ConditionValue().setUserEnteredValue("4/30/2016");
            BooleanCondition dateCondition = new BooleanCondition()
                    .setType("DATE_BEFORE")
                    .setValues(Collections.singletonList(dateValue));
            FilterCriteria criteria6 = new FilterCriteria().setCondition(dateCondition);

            // Map criteria to column indices (Note: keys are Strings in Java map)
            Map<String, FilterCriteria> criteriaMap = new HashMap<>();
            criteriaMap.put("0", criteria0);
            criteriaMap.put("6", criteria6);

            FilterView filterView = new FilterView()
                    .setTitle("Sample Filter")
                    .setRange(myRange)
                    .setSortSpecs(Collections.singletonList(
                            new SortSpec().setDimensionIndex(3).setSortOrder("DESCENDING")
                    ))
                    .setCriteria(criteriaMap);

            // --- Step 1: Add Filter View ---
            // (Request construction remains the same)
            // ...
            AddFilterViewRequest addFilterViewRequest = new AddFilterViewRequest().setFilter(filterView);

            BatchUpdateSpreadsheetRequest batchRequest1 = new BatchUpdateSpreadsheetRequest()
                    .setRequests(Collections.singletonList(new Request().setAddFilterView(addFilterViewRequest)));

            BatchUpdateSpreadsheetResponse response1 = service.spreadsheets()
                    .batchUpdate(spreadsheetId, batchRequest1)
                    .execute();

            if (response1.getReplies() == null || response1.getReplies().isEmpty()) {
                System.err.println("Error: No replies returned from AddFilterView request.");
                return;
            }

            Response reply1 = response1.getReplies().get(0);
            if (reply1.getAddFilterView() == null || reply1.getAddFilterView().getFilter() == null) {
                 System.err.println("Error: Response did not contain AddFilterView data.");
                 return;
            }

            int filterId = reply1.getAddFilterView().getFilter().getFilterViewId();

            // --- Step 2: Duplicate Filter View ---
            DuplicateFilterViewRequest duplicateRequest = new DuplicateFilterViewRequest()
                    .setFilterId(filterId);

            BatchUpdateSpreadsheetRequest batchRequest2 = new BatchUpdateSpreadsheetRequest()
                    .setRequests(Collections.singletonList(new Request().setDuplicateFilterView(duplicateRequest)));

            BatchUpdateSpreadsheetResponse response2 = service.spreadsheets()
                    .batchUpdate(spreadsheetId, batchRequest2)
                    .execute();

            if (response2.getReplies() == null || response2.getReplies().isEmpty()) {
                 System.err.println("Error: No replies returned from DuplicateFilterView request.");
                 return;
            }

            Response reply2 = response2.getReplies().get(0);
            if (reply2.getDuplicateFilterView() == null || reply2.getDuplicateFilterView().getFilter() == null) {
                System.err.println("Error: Response did not contain DuplicateFilterView data.");
                return;
            }

            int newFilterId = reply2.getDuplicateFilterView().getFilter().getFilterViewId();

            // --- Step 3: Update Filter View ---
            // Extract the new ID from the duplicate response
            int newFilterId = response2.getReplies().get(0)
                    .getDuplicateFilterView().getFilter().getFilterViewId();

            // Create update criteria
            Map<String, FilterCriteria> updateCriteriaMap = new HashMap<>();
            updateCriteriaMap.put("0", new FilterCriteria()); // Empty criteria

            ConditionValue numValue = new ConditionValue().setUserEnteredValue("5");
            BooleanCondition numCondition = new BooleanCondition()
                    .setType("NUMBER_GREATER")
                    .setValues(Collections.singletonList(numValue));
            updateCriteriaMap.put("3", new FilterCriteria().setCondition(numCondition));

            FilterView updateFilterView = new FilterView()
                    .setFilterViewId(newFilterId)
                    .setTitle("Updated Filter")
                    .setCriteria(updateCriteriaMap);

            UpdateFilterViewRequest updateRequest = new UpdateFilterViewRequest()
                    .setFilter(updateFilterView)
                    .setFields("criteria,title");

            BatchUpdateSpreadsheetRequest batchRequest3 = new BatchUpdateSpreadsheetRequest()
                    .setRequests(Collections.singletonList(new Request().setUpdateFilterView(updateRequest)));

            BatchUpdateSpreadsheetResponse response3 = service.spreadsheets()
                    .batchUpdate(spreadsheetId, batchRequest3)
                    .execute();

            System.out.println(response3.toPrettyString());

        } catch (IOException | GeneralSecurityException e) {
            System.err.println("An error occurred: " + e);
        }
    }
}

Python

sheets/snippets/sheets_filter_views.py
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def filter_views(spreadsheet_id):
  """
  Creates the batch_update the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)

    my_range = {
        "sheetId": 0,
        "startRowIndex": 0,
        "startColumnIndex": 0,
    }
    addfilterviewrequest = {
        "addFilterView": {
            "filter": {
                "title": "Sample Filter",
                "range": my_range,
                "sortSpecs": [{
                    "dimensionIndex": 3,
                    "sortOrder": "DESCENDING",
                }],
                "criteria": {
                    0: {"hiddenValues": ["Panel"]},
                    6: {
                        "condition": {
                            "type": "DATE_BEFORE",
                            "values": {"userEnteredValue": "4/30/2016"},
                        }
                    },
                },
            }
        }
    }

    body = {"requests": [addfilterviewrequest]}
    addfilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )

    duplicatefilterviewrequest = {
        "duplicateFilterView": {
            "filterId": addfilterviewresponse["replies"][0]["addFilterView"][
                "filter"
            ]["filterViewId"]
        }
    }

    body = {"requests": [duplicatefilterviewrequest]}
    duplicatefilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )

    updatefilterviewrequest = {
        "updateFilterView": {
            "filter": {
                "filterViewId": duplicatefilterviewresponse["replies"][0][
                    "duplicateFilterView"
                ]["filter"]["filterViewId"],
                "title": "Updated Filter",
                "criteria": {
                    0: {},
                    3: {
                        "condition": {
                            "type": "NUMBER_GREATER",
                            "values": {"userEnteredValue": "5"},
                        }
                    },
                },
            },
            "fields": {"paths": ["criteria", "title"]},
        }
    }

    body = {"requests": [updatefilterviewrequest]}
    updatefilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )
    print(str(updatefilterviewresponse))
  except HttpError as error:
    print(f"An error occurred: {error}")


if __name__ == "__main__":
  # Pass: spreadsheet_id
  filter_views("1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k")