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

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

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

בדוגמאות האלה, ערכי הפלייסהולדר SPREADSHEET_ID ו-SHEET_ID מציינים את המקומות שבהם צריך לספק את המזהים האלה. המזהה של הגיליון האלקטרוני מופיע בכתובת ה-URL של הגיליון האלקטרוני. אפשר לאתר את מזהה הגיליון באמצעות ה-method‏ 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 בגוף הבקשה מציין את גיליון היעד. העותק שומר על כל הערכים, העיצוב, הנוסחאות ומאפיינים אחרים של המקור. הכותרת של הגיליון המועתק מוגדרת כ'עותק של [הכותרת המקורית של הגיליון]'.

התשובה מורכבת מאובייקט 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_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
        }
      },
      ...
  ],
}