כתיבה בסיסית

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

שימו לב שאפשר גם לכתוב ערכי תאים באמצעות השיטה spreadsheet.batchUpdate, שיכולה להיות שימושית אם רוצים לעדכן בו-זמנית את עיצוב התא או מאפיינים אחרים שהמשאב spreadsheets.values לא משפיע עליהם. לדוגמה, אם רוצים להעתיק טווח של תאים מגיליון אחד לאחר ומחליפים גם את נוסחת התא וגם את עיצוב התא, אפשר להשתמש בשיטה UpdateCellsRequest עם spreadsheet.batchUpdate.

עם זאת, כשכותבים ערכים פשוטים קל יותר להשתמש ב-method spreadsheets.values.update או ב-method spreadsheets.values.batchUpdate.

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

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

כתיבת טווח יחיד

נתחיל עם גיליון אלקטרוני ריק חדש, דוגמת הקוד הבאה של spreadsheets.values.update מראה איך לכתוב את הערכים בטווח. פרמטר השאילתה ValueInputOption נדרש והוא קובע אם הערכים שנכתבו ינותחו (לדוגמה, אם מחרוזת מומרת לתאריך).

גוף הבקשה הוא אובייקט ValueRange שמתאר את ערכי הטווח לכתיבה. השדה majorDimension מציין שמערכים הם רשימות של ערכים שמאורגנות לפי שורות. הערכים הקיימים בטווח היעד מוחלפים.

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

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

התגובה מורכבת מאובייקט UpdateValuesResponse, כמו זה:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

הגיליון שמתקבל נראה כך:

	A	B	C	D
1	פריט	עלות	מלא	תאריך משלוח
2	גלגל ענק	82 ש"ח	4	01.03.2016
3	דלת	60 ש"ח	2	15.03.2016
4	מנוע	400 ש"ח	1	20.03.2016
5	סה"כ	520 ש"ח	7	20.03.2016

כתיבה סלקטיבית על טווח

כשכותבים ערכים לטווח, אפשר להימנע משינוי של חלק מהתאים הקיימים על ידי הגדרת רכיבי המערך המתאימים ל-null. יש גם אפשרות לנקות תא על ידי כתיבת מחרוזת ריקה ("").

נתחיל בגיליון שמכיל את אותם נתונים שנוצרו בדוגמה שלמעלה, דוגמת הקוד הבאה של spreadsheets.values.update מראה איך לכתוב את הערכים בטווח B1:D4, תוך השארת תאים סלקטיביים ללא שינוי וניקוי תאים אחרים. פרמטר השאילתה ValueInputOption נדרש והוא קובע אם הערכים שנכתבו ינותחו (לדוגמה, אם מחרוזת מומרת לתאריך).

גוף הבקשה הוא אובייקט ValueRange שמתאר את ערכי הטווח לכתיבה. השדה majorDimension מציין שמערכים הם רשימות של ערכים שמאורגנים לפי עמודה.

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

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

השדה values כאן מפרט את השינויים שבוצעו בכל עמודה בטווח. המערך הראשון מציין שצריך להשאיר את B1 ללא שינוי (בגלל רכיב המערך null), ואת B4 צריך למחוק (מחרוזת ריקה). הערכים של B2 ו-B3 מתעדכנים. המערך השלישי מבצע את אותן הפעולות בעמודה D, והמערך הריק השני מציין שעמודה C צריכה להישאר ללא שינוי.

התגובה מורכבת מאובייקט UpdateValuesResponse, כמו זה:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

הגיליון שמתקבל נראה כך:

	A	B	C	D
1	פריט	עלות	מלא	תאריך משלוח
2	גלגל ענק	4 ש"ח	4	01.04.2016
3	דלת	2$‎	2	15.04.2016
4	מנוע		1
5	סה"כ	12.00 ש"ח	7	15.04.2016

שימו לב שהשורה 'סכומים' לא השתנתה ישירות בעקבות הבקשה הזו, כי התאים בה מכילים נוסחאות שתלויות בתאים שהשתנו.

כתיבה למספר טווחים

נתחיל עם גיליון ריק, דוגמת הקוד הבאה spreadsheets.values.batchUpdate מראה איך לכתוב את הערכים בטווחים Sheet1!A1:A4 ו-Sheet1!B1:D2. הערכים הקיימים בטווח היעד יוחלפו. גוף הבקשה מורכב מאובייקט ValueInputOption שמראה איך לפרש את נתוני הקלט, וממערך של אובייקטים מסוג ValueRange שתואמים לכל טווח שנכתב. השדה majorDimension קובע אם המערכים הכלולים יפורשו כמערכי עמודות או שורות.

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

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

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

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

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

הגיליון שמתקבל נראה כך:

	A	B	C	D
1	פריט	עלות	מלא	תאריך משלוח
2	גלגל ענק	82 ש"ח	4	01.03.2016
3	דלת
4	מנוע
5

כתיבת ערכים ללא ניתוח

נתחיל עם גיליון ריק, דוגמת הקוד הבאה של spreadsheets.values.update מראה איך לכתוב את הערכים בטווח Sheet1!A1:E1, אבל משתמשת בפרמטר השאילתה RAW ValueInputOption כדי למנוע ניתוח של המחרוזות הכתובות כנוסחאות, בוליאניים או מספרים. הם מופיעים כמחרוזות והיישור של הטקסט מיושר בגיליון.

גוף הבקשה הוא אובייקט ValueRange שמתאר את ערכי הטווח לכתיבה. השדה majorDimension מציין שמערכים הם רשימות של ערכים שמאורגנות לפי שורות. הערכים הקיימים בטווח היעד מוחלפים.

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

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

התגובה מורכבת מאובייקט UpdateValuesResponse, כמו זה:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

הגיליון שמתקבל נראה כך:

	A	B	C	D	ה.
1	נתונים	123.45	TRUE	=MAX(D2:D4)	10
2

שים לב ש-TRUE הוא ממורכז והוא ערך בוליאני, ואילו 123.45 הוא ערך ישר כי הוא מספר, ו-10 הוא מחרוזת משמאל הנוסחה לא תנותח, אלא גם תופיע כמחרוזת.

צירוף ערכים

מתחילים בגיליון כמו הטבלה הבאה:

	A	B	C	D
1	פריט	עלות	מלא	תאריך משלוח
2	גלגל ענק	82 ש"ח	4	01.03.2016
3

דוגמת הקוד הבאה של spreadsheets.values.append מראה איך להוסיף שתי שורות חדשות של ערכים שמתחילות משורה 3. פרמטר השאילתה ValueInputOption נדרש והוא קובע אם הערכים שנכתבו ינותחו (לדוגמה, אם מחרוזת מומרת לתאריך).

גוף הבקשה הוא אובייקט ValueRange שמתאר את ערכי הטווח לכתיבה. השדה majorDimension מציין שמערכים הם רשימות של ערכים שמאורגנות לפי שורות.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

התגובה מורכבת מאובייקט AppendValuesResponse, כמו זה:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

הגיליון שמתקבל נראה כך:

	A	B	C	D
1	פריט	עלות	מלא	תאריך משלוח
2	גלגל ענק	82 ש"ח	4	01.03.2016
3	דלת	60 ש"ח	2	15.03.2016
4	מנוע	400 ש"ח	1	20.03.2016
5