כתיבה בסיסית

‫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

שימו לב שהשורה 'סכומים כוללים' משתנה, למרות שהיא לא משתנה ישירות בגלל הבקשה הזו, כי התאים שלה מכילים נוסחאות שתלויות בתאים שהשתנו.

כתיבה לכמה טווחים

בדוגמת הקוד הבאה, שמתחילה בגיליון ריק, אפשר לראות איך לכתוב את הערכים בטווחים Sheet1!A1:A4 ו-Sheet1!B1:D2.spreadsheets.values.batchUpdate הערכים הקיימים בטווח היעד מוחלפים. גוף הבקשה מורכב מאובייקט 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