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

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

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

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

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