מסננים

המסננים מאפשרים למיין ולסנן את הנתונים שמוצגים כשמציגים גיליון אלקטרוני. המסננים לא משנים את ערכי הנתונים בגיליון האלקטרוני. אפשר להשתמש במסננים כדי להסתיר או למיין מידע באופן זמני. נתונים שתואמים לקריטריוני הסינון שצוינו לא מופיעים כשהמסנן מופעל. באמצעות תצוגות מסנן, אפשר גם לשמור מסננים שונים עם שמות ולעבור ביניהם מתי שרוצים.

הנה כמה תרחישי שימוש לדוגמה במסננים:

  • למיין את הנתונים לפי עמודה מסוימת. לדוגמה, מיון רשומות משתמשים לפי שם משפחה.
  • הסתרת נתונים שעומדים בתנאי מסוים. לדוגמה, להסתיר את כל הרשומות מלפני יותר משנתיים.
  • הסתרת נתונים שתואמים לערך מסוים. לדוגמה, להסתיר את כל הבעיות עם הסטטוס 'נסגר'.

מסנן בסיסי

המסנן שמוגדר כברירת מחדל לגיליון אלקטרוני הוא המסנן שמופעל בכל פעם שמישהו צופה בגיליון האלקטרוני.BasicFilter בכל גיליון יכול להיות מסנן בסיסי אחד. כדי להשבית את המסנן הבסיסי, צריך לבטל את הסימון שלו. הפעולה הזו מסירה את המסנן ואת כל ההגדרות שלו מגיליון האלקטרוני. אם רוצים להפעיל מחדש את אותו מסנן, צריך להגדיר שוב את הקריטריונים.

ניהול המסנן הבסיסי

כדי להגדיר או לבטל את המסנן הבסיסי, משתמשים בשיטה spreadsheets.batchUpdate עם סוג הבקשה המתאים:

כדי להציג את המסנן הבסיסי, משתמשים בשיטה spreadsheets.get ומגדירים את הפרמטר fields של כתובת ה-URL לערך sheets/basicFilter. בדוגמת הקוד הבאה, spreadsheets.getמוצגת כתובת URL של Google Sheets עם field mask:

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

תצוגות מסנן

FilterView הוא מסנן עם שם שאפשר להפעיל או להשבית מתי שרוצים. בגיליון אלקטרוני יכולות להיות כמה תצוגות מסנן, אבל אפשר להחיל רק אחת בכל פעם.

הנה כמה תרחישי שימוש לדוגמה בתצוגות סינון:

  • יש לכם כמה מסננים שונים שאתם רוצים לעבור ביניהם כשאתם צופים בנתונים.
  • לסנן גיליון אלקטרוני שאין לכם גישת עריכה אליו. במקרה כזה, אפשר ליצור תצוגת מסנן זמנית שרק אתם יכולים לראות.

  • אתם רוצים שכל אדם שאתם משתפים איתו את הגיליון האלקטרוני יראה את הנתונים בצורה שונה. כדי לציין את התצוגה המסוננת שרוצים להחיל, צריך לספק את spreadsheetId ואת filterViewId בכתובת ה-URL של הגיליון האלקטרוני. כדי לעשות זאת, משתמשים ב-filterViewId שמוחזר בתגובה כשיוצרים את תצוגת הסינון.

    בדוגמה הבאה של קוד מוצגת כתובת URL של Google Sheets עם תצוגת סינון:

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

ניהול תצוגות מסוננות

כדי ליצור, לשכפל, לשנות או למחוק תצוגות מסוננות, משתמשים בשיטה spreadsheets.batchUpdate עם סוג הבקשה המתאים:

כדי להציג רשימה של כל התצוגות המפורטות עם מסננים, משתמשים בשיטה spreadsheets.get ומגדירים את פרמטר כתובת ה-URL‏ fields לערך sheets/filterViews. בדוגמת הקוד הבאה, spreadsheets.getמוצגת כתובת URL של Google Sheets עם field mask:

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

ייצוג של מסנן

בדוגמה הבאה מוצג ייצוג ה-JSON של אובייקט FilterView. אובייקט 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 מערב Beth 01/03/2016
3 דלת D-01X $15.00 2 דרום Amir 15/03/2016
4 מסגרת FR-0B1 $34.00 8 מזרח חנה 12/03/2016
5 חלונית P-034 24.00 ש"ח 4 צפון Devyn 15/03/2016
6 חלונית P-052 ‪11.50$ 7 מזרח אריק 16/05/2016
7 גלגל ענק W-24 $20.50 11 דרום Sheldon 30/04/2016
8 מנוע ENG-0161 $330.00 2 צפון Jessie 02/07/2016

מיון המפרטים

מסנן יכול לכלול כמה הגדרות מיון. המפרטים האלה קובעים איך למיין את הנתונים, והם מוחלים לפי הסדר שצוין. המאפיין SortSpec.dimensionIndex מציין את אינדקס העמודה שאליה יחול המיון.

בדוגמת הקוד הבאה מוצגת הגדרת מיון:

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

כשמחילים את המפרט הזה על נתוני המכירות לדוגמה, המערכת ממיינת קודם לפי 'כמות', ואם יש 2 שורות עם אותה כמות, היא ממיינת לפי 'תאריך המשלוח'.

טבלה 2. נתוני מכירות ממוינים לפי 2 עמודות
A B C D E F G
1 קטגוריית פריט מספר הדגם עלות כמות אזור אנשי מכירות תאריך משלוח
2 דלת D-01X $15.00 2 דרום Amir 15/03/2016
3 מנוע ENG-0161 $330.00 2 צפון Jessie 02/07/2016
4 גלגל ענק W-24 $20.50 4 מערב Beth 01/03/2016
5 חלונית P-034 24.00 ש"ח 4 צפון Devyn 15/03/2016
6 חלונית P-052 ‪11.50$ 7 מזרח אריק 16/05/2016
7 מסגרת FR-0B1 $34.00 8 מזרח חנה 12/03/2016
8 גלגל ענק W-24 $20.50 11 דרום Sheldon 30/04/2016

קריטריוני סינון

השיטה FilterCriteria קובעת אילו נתונים מגיליון אלקטרוני יוצגו או יוסתרו במסנן בסיסי או בתצוגת מסנן. כל קריטריון תלוי בערכים בעמודה ספציפית. אתם מספקים את קריטריוני הסינון כמפה שבה המפתחות הם אינדקסים של עמודות והערכים הם הקריטריונים.

אם הקריטריון מוגדר באמצעות ערך בוליאני condition, התנאי חייב להיות True כדי שהערכים יוצגו. התנאי לא מבטל את hiddenValues. אם ערך מופיע ב-hiddenValues, כל ההתאמות לערך עדיין מוסתרות.

בדוגמת הקוד הבאה מוצגת מפה של קריטריונים לסינון:

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

כשמחילים את הקריטריונים האלה על נתוני המכירות לדוגמה, מוצגות רק השורות שבהן הערך של 'קטגוריית פריט' הוא לא 'לוח', והערך של 'תאריך המשלוח' הוא לפני 30 באפריל 2016.

טבלה 3. נתוני מכירות באמצעות קריטריונים לסינון
A B C D E F G
1 קטגוריית פריט מספר הדגם עלות כמות אזור אנשי מכירות תאריך משלוח
2 גלגל ענק W-24 $20.50 4 מערב Beth 01/03/2016
3 דלת D-01X $15.00 2 דרום Amir 15/03/2016
4 מסגרת FR-0B1 $34.00 8 מזרח חנה 12/03/2016

דוגמה

בדוגמת הקוד הבאה מוצגות הפעולות הבאות: יצירת תצוגת מסנן, שכפול שלה ועדכון הגרסה המשוכפלת באמצעות נתוני המכירות לדוגמה שמופיעים למעלה.

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