כתיבה בסיסית

ב-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