כתיבה בסיסית

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

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

אבל בכתיבה פשוטה של ערכים, קל יותר להשתמש spreadsheets.values.update או 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	מנוע	400 ש"ח	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 ש"ח	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" נשאר מוצדק כי String. הנוסחה לא מנותחת והיא מופיעה גם כמחרוזת.

צירוף ערכים

מתחילים בגיליון כמו הטבלה הבאה:

	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	מנוע	400 ש"ח	1	20.03.2016
5