Google Sheets API מאפשר לכתוב ערכים ונוסחאות לתאים, לטווחים,
קבוצות של טווחים וגיליונות שלמים. הדוגמאות בדף הזה ממחישות איך
אפשר לבצע פעולות כתיבה נפוצות באמצעות
spreadsheets.values
של Sheets API.
לתשומת ליבך, אפשר גם לכתוב ערכי תאים באמצעות
spreadsheet.batchUpdate
השיטה הזו יכולה להיות שימושית אם רוצים לעדכן בו-זמנית את העיצוב של התא
או נכסים אחרים,
spreadsheets.values
למשאב הזה לא משפיע. לדוגמה, אם רוצים להעתיק טווח של תאים מ-
בגיליון אחר, תוך החלפת נוסחת התא והתא
אפשר להשתמש בפורמט
UpdateCellsRequest
עם
spreadsheet.batchUpdate
אבל בכתיבה פשוטה של ערכים, קל יותר להשתמש
spreadsheets.values.update
או
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 | מנוע | 400 ש"ח | 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 ש"ח | 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" נשאר מוצדק כי String. הנוסחה לא מנותחת והיא מופיעה גם כמחרוזת.
צירוף ערכים
מתחילים בגיליון כמו הטבלה הבאה:
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 | מנוע | 400 ש"ח | 1 | 20.03.2016 |
5 |