כתיבה בסיסית

‫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,
}

הגיליון שיתקבל ייראה כך:

כתיבה סלקטיבית לטווח

כשכותבים ערכים לטווח, אפשר להימנע משינוי של תאים קיימים מסוימים על ידי הגדרת הרכיבים התואמים במערך כ-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,
}

הגיליון שיתקבל ייראה כך:

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

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

בדוגמת הקוד הבאה 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,
    }
  ],
}

הגיליון שיתקבל ייראה כך:

כתיבת ערכים בלי ניתוח

בדוגמת הקוד הבאה 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,
}

הגיליון שיתקבל ייראה כך:

שימו לב שהערך TRUE מיושר למרכז והוא ערך בוליאני, בעוד שהערך 123.45 מיושר לימין כי הוא מספר, והערך 10 מיושר לשמאל כי הוא מחרוזת. הנוסחה לא מנותחת ומופיעה גם כמחרוזת.

הוספת ערכים

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

בדוגמת הקוד הבאה 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,
  }
}

הגיליון שיתקבל ייראה כך: