כתיבה בסיסית

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

שימו לב שאפשר גם לכתוב ערכים של תאים באמצעות השיטה 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	1.3.2016
3	דלת	60 ש"ח	2	15.03.2016
4	מנוע	400 ש"ח	1	20/03/2016
5	סה"כ	135.5$	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	1.3.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	1.3.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	1.3.2016
3	דלת	60 ש"ח	2	15.03.2016
4	מנוע	400 ש"ח	1	20/03/2016
5