ב-Google Sheets API אפשר לכתוב ערכים ונוסחאות לתאים, לטווחים, לקבוצות של טווחים ולגיליונות שלמים. הדוגמאות בדף הזה ממחישות איך אפשר לבצע פעולות כתיבה נפוצות באמצעות המשאב spreadsheets.values
של Sheets API.
שימו לב שאפשר גם לכתוב ערכי תאים באמצעות method spreadsheet.batchUpdate
, שיכולה להיות שימושית אם רוצים לעדכן בו-זמנית את עיצוב התא או מאפיינים אחרים שהמשאב spreadsheets.values
לא משפיע עליהם. לדוגמה, אם רוצים להעתיק טווח של תאים מגיליון אחד לגיליון אחר תוך החלפת נוסחת התא ועיצוב התא, אפשר להשתמש ב-method 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.00 ש"ח | 4 | 01.03.2016 |
3 | דלת | 60 ש"ח | 2 | 15.03.2016 |
4 | מנוע | 100$ | 1 | 20.03.2016 |
5 | סה"כ | 543.0 ש"ח | 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.00 ש"ח | 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 | E | |
1 | נתונים | 123.45 | TRUE | =MAX(D2:D4) | 10 |
2 |
שימו לב ש-"TRUE" הוא ערך בוליאני, ואילו 123.45 ישר כי הוא מספר ו-10 ישר ישר שמאלה כי זו מחרוזת. הנוסחה לא מנותחת והיא מופיעה גם כמחרוזת.
צירוף ערכים
מתחילים בגיליון כמו הטבלה הבאה:
A | B | C | D | |
1 | פריט | עלות | מלאי | תאריך משלוח |
2 | גלגל ענק | 82.00 ש"ח | 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.00 ש"ח | 4 | 01.03.2016 |
3 | דלת | 60 ש"ח | 2 | 15.03.2016 |
4 | מנוע | 100$ | 1 | 20.03.2016 |
5 |