פעולות בגיליון

ב-Google Sheets API אפשר ליצור, לנקות, להעתיק ולמחוק גיליונות, וגם לשלוט במאפיינים שלהם. הדוגמאות בדף הזה ממחישות איך אפשר לבצע כמה פעולות נפוצות ב-Sheets באמצעות ה-API של Sheets.

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

בדוגמאות האלה, ערכי ה-placeholder SPREADSHEET_ID ו-SHEET_ID מציינים איפה הייתם מספקים את המזהים האלה. המזהה של הגיליון האלקטרוני מופיע בכתובת ה-URL של הגיליון האלקטרוני. אפשר לאתר את מזהה הגיליון באמצעות השיטה spreadsheets.get. הטווחים מצוינים באמצעות סימון A1. טווח לדוגמה הוא Sheet1!A1:D5.

הוספת גיליון

דוגמת הקוד הבאה של spreadsheets.batchUpdate מראה איך להשתמש ב-AddSheetRequest כדי להוסיף גיליון לגיליון אלקטרוני, תוך הגדרת הכותרת, גודל הרשת וצבע הכרטיסייה.

התגובה מורכבת מ-AddSheetResponse, שמכיל אובייקט עם המאפיינים של הגיליון שנוצר (כמו SHEET_ID).

פרוטוקול הבקשה מוצג בהמשך.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "Deposits",
          "gridProperties": {
            "rowCount": 20,
            "columnCount": 12
          },
          "tabColor": {
            "red": 1.0,
            "green": 0.3,
            "blue": 0.4
          }
        }
      }
    }
  ]
}

ניקוי גיליון של כל הערכים תוך שימור הפורמטים

דוגמת הקוד הבאה של spreadsheets.batchUpdate מראה איך להשתמש ב-UpdateCellsRequest כדי להסיר את כל הערכים מהגיליון בלי לשנות את העיצוב.

ציון השדה userEnteredValue ללא ערך מתאים מפורש כהוראה לניקוי ערכים בטווח. אפשר להשתמש בהגדרה הזו גם בשדות אחרים. לדוגמה, שינוי הערך fields ל-userEnteredFormat מסיר מהגיליון את כל הפורמטים שנתמכים על ידי Sheets API, אבל משאיר את ערכי התא ללא שינוי.

פרוטוקול הבקשה מוצג בהמשך.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "updateCells": {
        "range": {
          "sheetId": SHEET_ID
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

העתקה של גיליון מגיליון אלקטרוני אחד לאחר

דוגמת הקוד הבאה של spreadsheet.sheets.copyTo מראה איך להעתיק גיליון יחיד שצוין על ידי SHEET_ID מגיליון אלקטרוני אחד לגיליון אלקטרוני אחר.

המשתנה TARGET_SPREADSHEET_ID בגוף הבקשה מציין את גיליון היעד של הגיליון האלקטרוני. העותק שומר את כל הערכים, העיצוב, הנוסחאות ושאר המאפיינים של המקור. הכותרת של הגיליון שהועתק מוגדרת כ-'Copy of [כותרת הגיליון המקורית]'.

התגובה מורכבת מאובייקט SheetProperties שמתאר את המאפיינים של הגיליון שנוצר.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/sheets/SHEET_ID:copyTo

{
  "destinationSpreadsheetId": "TARGET_SPREADSHEET_ID"
}

מחיקת גיליון

דוגמת הקוד הבאה של spreadsheets.batchUpdate מראה איך להשתמש ב-DeleteSheetRequest כדי למחוק גיליון שצוין על ידי SHEET_ID.

פרוטוקול הבקשה מוצג בהמשך.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": SHEET_ID
      }
    }
  ]
}

קריאת נתוני הגיליון

דוגמת הקוד הבאה spreadsheets.get מראה איך לקבל את פרטי המאפיין sheet מגיליון אלקטרוני, שמצוין ב-SHEET_ID וב-SPREADSHEET_ID. לעיתים קרובות משתמשים בשיטה הזו כדי לקבוע את המטא-נתונים של גיליונות בתוך גיליון אלקטרוני ספציפי, כדי שפעולות נוספות יוכלו לטרגט את הגיליונות האלה. פרמטר השאילתה fields מציין שצריך להחזיר רק נתונים של מאפיין גיליון (בניגוד לנתוני ערך תא או נתונים שקשורים לכל הגיליון האלקטרוני).

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

התגובה מורכבת ממשאב Spreadsheet שמכיל אובייקט Sheet עם רכיבי SheetProperties. אם שדה מסוים בתשובה מוגדר לערך ברירת המחדל, הוא לא ייכלל בתשובה.

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "Sheet1",
        "index": 0,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 100,
          "columnCount": 20,
          "frozenRowCount": 1
        }
        "tabColor": {
          "blue": 1.0
        }
      },
      ...
  ],
}