כתיבה בסיסית

באמצעות 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	גלגל ענק	20.50$‎	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	1.4.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	גלגל ענק	20.50$‎	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	גלגל ענק	20.50$‎	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	גלגל ענק	20.50$‎	4	1.3.2016
3	דלת	60 ש"ח	2	15/03/2016
4	מנוע	400 ש"ח	1	20/03/2016
5