Esta página foi traduzida pela API Cloud Translation.

Filtros

Os filtros permitem classificar e filtrar os dados que você vê quando visualiza uma planilha. Os filtros não alteram os valores dos dados na sua planilha. Você pode usar filtros para ocultar ou classificar temporariamente as informações. Os dados que correspondem aos critérios de filtro especificados não aparecem enquanto o filtro está ativado. Com as visualizações de filtros, também é possível salvar diferentes filtros nomeados e alternar entre eles sempre que quiser.

Veja a seguir alguns exemplos de casos de uso de filtros:

Classificando os dados por uma coluna específica. Por exemplo, classifique os registros do usuário pelo sobrenome.
Ocultar dados que atendem a uma condição específica. Por exemplo, oculte todos os registros com mais de 2 anos.
Ocultar dados que correspondem a um determinado valor. Por exemplo, oculte todos os problemas com status "fechado".

Filtro básico

O BasicFilter de uma planilha é o filtro padrão aplicado sempre que alguém visualiza a planilha. Uma planilha pode ter um filtro básico por planilha. Você pode desativar o filtro básico limpando-o. Assim, o filtro e todas as configurações dele serão removidos da planilha. Para reativar o mesmo filtro, defina os critérios outra vez.

Gerenciar o filtro básico

Para definir ou limpar o filtro básico, use o método spreadsheets.batchUpdate com o tipo de solicitação apropriado:

Para definir o filtro básico, use o método SetBasicFilterRequest.
Para limpar o filtro básico, use o método ClearBasicFilterRequest.

Para listar o filtro básico, use o método spreadsheets.get e defina o parâmetro de URL fields como sheets/basicFilter. O exemplo de código spreadsheets.get a seguir mostra um URL das Planilhas Google com uma máscara de campo:

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

Visualizações com filtro

Um FilterView é um filtro nomeado que você pode desativar e ativar sempre que quiser. Uma planilha pode ter várias visualizações de filtro, mas você só pode aplicar uma de cada vez.

Veja a seguir alguns exemplos de casos de uso para visualizações com filtro:

Você tem vários filtros diferentes para alternar ao visualizar os dados.
Você não tem acesso para editar uma planilha, mas ainda quer aplicar um filtro. Nesse caso, crie uma visualização de filtro temporária que seja visível apenas para você.
Você quer que cada pessoa com quem você compartilha sua planilha visualize os dados de maneira diferente. Você pode especificar a visualização de filtro que quer aplicar fornecendo spreadsheetId e filterViewId no URL da planilha. Para isso, use o filterViewId retornado na resposta ao criar a visualização de filtro.

O exemplo de código a seguir mostra um URL do Planilhas Google com uma visualização de filtro:
```
https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0&fvid=FILTER_VIEW_ID
```

Gerenciar visualizações com filtro

Para criar, duplicar, modificar ou excluir visualizações de filtro, use o método spreadsheets.batchUpdate com o tipo de solicitação apropriado:

Para criar uma visualização com filtro, use o método AddFilterViewRequest.
Para fazer uma cópia de uma visualização de filtro, use o método DuplicateFilterViewRequest.
Para modificar as propriedades de uma visualização de filtro, use o método UpdateFilterViewRequest.
Para excluir uma visualização de filtro, use o método DeleteFilterViewRequest.

Para listar todas as visualizações de filtro, use o método spreadsheets.get e defina o parâmetro de URL fields como sheets/filterViews. O exemplo de código spreadsheets.get a seguir mostra um URL das Planilhas Google com uma máscara de campo:

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

Representação de filtro

O exemplo de código a seguir mostra a representação JSON de um objeto FilterView. O objeto BasicFilter é o mesmo, mas não tem os campos filterViewId e title e não pode usar um intervalo nomeado.

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

Exemplo

O restante deste documento faz referência ao exemplo de tabela de dados de vendas abaixo:

**Tabela 1.** Exemplo de dados de vendas
	A	B	C	D	E	F	G
1	Categoria do item	Número do modelo	Custo	Quantidade	Região	Vendedor	Data de envio
2	Roda gigante	W-24	US$ 20,50	4	Oeste	Beth	01/03/2016
3	Porta	Dado	US$ 15,00	2	Sul	Amir	15/03/2016
4	Quadro	FR-0B1	US$ 34,00	8	Leste	Hannah	12/03/2016
5	Painel	P-034	US$ 6,00	4	Norte	Devyn	15/03/2016
6	Painel	P-052	US$ 11,50	7	Leste	Erik	16/05/2016
7	Roda gigante	W-24	US$ 20,50	11	Sul	Sheldon	30/04/2016
8	Mecanismo	ENG-0161	US$ 330,00	2	Norte	Jéssica	02/07/2016

Ordenar especificações

Um filtro pode ter várias especificações de classificação. Essas especificações determinam como classificar os dados e são aplicadas na ordem especificada. O atributo SortSpec.dimensionIndex especifica o índice da coluna ao qual a classificação precisa ser aplicada.

O exemplo de código a seguir mostra uma especificação de classificação:

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

Quando aplicada aos dados de vendas de exemplo, essa especificação classifica por "Quantidade" primeiro e, em seguida, se duas linhas tiverem a mesma quantidade, por "Data de envio".

**Tabela 2.** Dados de vendas classificados por duas colunas
	A	B	C	D	E	F	G
1	Categoria do item	Número do modelo	Custo	Quantidade	Região	Vendedor	Data de envio
2	Porta	Dado	US$ 15,00	2	Sul	Amir	15/03/2016
3	Mecanismo	ENG-0161	US$ 330,00	2	Norte	Jéssica	02/07/2016
4	Roda gigante	W-24	US$ 20,50	4	Oeste	Beth	01/03/2016
5	Painel	P-034	US$ 6,00	4	Norte	Devyn	15/03/2016
6	Painel	P-052	US$ 11,50	7	Leste	Erik	16/05/2016
7	Quadro	FR-0B1	US$ 34,00	8	Leste	Hannah	12/03/2016
8	Roda gigante	W-24	US$ 20,50	11	Sul	Sheldon	30/04/2016

Filtrar critérios

O método FilterCriteria determina quais dados da planilha são mostrados ou ocultados em um filtro básico ou uma visualização de filtro. Cada critério depende dos valores em uma coluna específica. Forneça os critérios de filtro como um mapa, em que as chaves são os índices de coluna e os valores são os critérios.

Para critérios especificados com um booleano condition, a condição precisa ser True para que os valores sejam exibidos. A condição não modifica hiddenValues. Se um valor estiver listado em hiddenValues, todas as correspondências de um valor ainda estarão ocultas.

O exemplo de código a seguir mostra um mapa de critérios de filtro:

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

Quando aplicados aos dados de vendas de exemplo, esses critérios mostram apenas as linhas em que a "Categoria do item" não é "Painel" e a "Data de envio" é anterior a 30 de abril de 2016.

**Tabela 3.** Dados de vendas usando critérios do filtro
	A	B	C	D	E	F	G
1	Categoria do item	Número do modelo	Custo	Quantidade	Região	Vendedor	Data de envio
2	Roda gigante	W-24	US$ 20,50	4	Oeste	Beth	01/03/2016
3	Porta	Dado	US$ 15,00	2	Sul	Amir	15/03/2016
4	Quadro	FR-0B1	US$ 34,00	8	Leste	Hannah	12/03/2016

Exemplo

O exemplo de código a seguir mostra como criar uma visualização de filtro, duplicá-la e atualizar a versão duplicada usando os dados de vendas de exemplo acima.

Python

sheets/snippets/sheets_filter_views.py

Ver no GitHub

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")