כתיבה בסיסית

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

שימו לב שאפשר גם לכתוב ערכים בתאים באמצעות השיטה spreadsheet.batchUpdate, שיכולה להיות שימושית אם רוצים לעדכן בו-זמנית את העיצוב של התאים או מאפיינים אחרים שלא מושפעים מהמשאב spreadsheets.values. לדוגמה, אם רוצים להעתיק טווח תאים מגיליון אחד לגיליון אחר ולדרוס גם את הנוסחה בתא וגם את העיצוב של התא, אפשר להשתמש בשיטה UpdateCellsRequest עם spreadsheet.batchUpdate.

עם זאת, כדי לכתוב ערכים פשוטים, קל יותר להשתמש בשיטה spreadsheets.values.update או בשיטה spreadsheets.values.batchUpdate.

הדוגמאות האלה מוצגות בצורה של בקשות HTTP כדי להיות ניטרליות מבחינת שפה. כדי ללמוד איך להטמיע פעולות כתיבה בשפות שונות באמצעות ספריות הלקוח של Google API, אפשר לעיין במאמר קריאה וכתיבה של ערכי תאים.

בדוגמאות האלה, הפלייס הולדר 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	01/03/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	גלגל ענק	$20.50	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	גלגל ענק	$20.50	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	גלגל ענק	$20.50	4	01/03/2016
3	דלת	60 ש"ח	2	15/03/2016
4	מנוע	400 ש"ח	1	20/03/2016
5