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 |