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

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

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

בדוגמאות האלה, ה-placeholders 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 [Original Sheet title]".

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