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

באמצעות 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 מגיליון אלקטרוני, שצוין על ידי 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
        }
      },
      ...
  ],
}